coremlit 0.2.0

use std::path::PathBuf;

use super::*;
use crate::audio::whisper::{
  audio::vad::VoiceActivityDetector,
  backend::{ModelDims, mock::MockBackend},
  error::{SegmentError, TranscribeError, VadError},
  options::{AlignmentGather, ChunkingStrategy, DecodingOptions},
  tokenizer::{SpecialTokens, WhisperTokenizer},
};

fn tiny_tokenizer() -> WhisperTokenizer {
  let root = std::env::var_os("WHISPERKIT_TEST_MODELS")
    .map_or_else(crate::tests::models_root, PathBuf::from);
  WhisperTokenizer::from_folder(root.join("tokenizers/whisper-tiny")).unwrap()
}

fn special() -> SpecialTokens {
  SpecialTokens::whisper_defaults()
}

fn ts(index: u32) -> u32 {
  special().time_token_begin() + index
}

/// One clean scripted window: prompt predictions + " Hello" + closing
/// timestamps + EOT. Timestamp pair <|0.00|> .. <|2.00|>.
fn script_clean_window(mock: &mut MockBackend, word: u32) {
  let s = special();
  mock.push_token_steps(&[
    s.english_token(),
    s.transcribe_token(),
    ts(0),
    word,
    ts(100),
    ts(100),
    s.end_token(),
  ]);
}

/// [`script_clean_window`] with an alignment row per step (the mock's
/// `n_audio_ctx` must be 100), each peaking one 20 ms frame later than the
/// last, so the word timing places `word` a tenth of a second into the
/// window — what a window a clip under the padding decodes attributes its
/// text by, on the default options too.
fn script_clean_window_aligned(mock: &mut MockBackend, word: u32) {
  let s = special();
  let script = [
    s.english_token(),
    s.transcribe_token(),
    ts(0),
    word,
    ts(100),
    ts(100),
    s.end_token(),
  ];
  for (step, token) in script.iter().enumerate() {
    let mut row = vec![0.0f32; 100];
    row[step + 1] = 1.0;
    mock.push_step_with_alignment(one_hot(*token), row);
  }
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn audio_shorter_than_window_clip_time_decodes_one_window_clipped_to_it() {
  // mediagraph#536: Swift's guard `while seek < seekClipEnd - windowPadding`
  // (TranscribeTask.swift:113-116) never runs for audio shorter than
  // windowClipTime (1 s default). This port opens the clip's first window
  // anyway (`opens_window`): 0.9 s of audio decodes once, and the scripted
  // `<|0.00|> Hello <|2.00|>` segment — timed 1.1 s into the padding — is
  // clipped back to the audio (`clip_back_to_window`).
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window_aligned(&mut mock, hello);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 14_400], &DecodingOptions::new())
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 1, "one window, not none");
  assert_eq!(result.text(), "Hello");
  assert_eq!(result.segments_slice().len(), 1);
  let segment = &result.segments_slice()[0];
  assert!((segment.start() - 0.0).abs() < 1e-4);
  assert!(
    (segment.end() - 0.9).abs() < 1e-4,
    "clipped back to the 0.9 s of audio, got {}",
    segment.end()
  );
}

/// Three clips over 6 s of audio — a 0.4 s word, a 0.75 s word and a 1.55 s
/// control, the shapes mediagraph#536 measured — each decode one window. The
/// two under the 1 s padding (Swift decoded neither) have their scripted
/// `<|0.00|> .. <|2.00|>` segment clipped back to the clip; the control,
/// which Swift decodes too, keeps the model's timing, as it always has.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn short_clips_each_decode_one_window_clipped_to_their_bounds() {
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(48_000)
      .with_n_audio_ctx(100),
  );
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window_aligned(&mut mock, hello);
  let task = TranscribeTask::new(&mock, &t);
  let clips = [(0.5_f32, 0.9_f32), (1.9, 2.65), (3.65, 5.2)];
  let options = DecodingOptions::new().with_clip_timestamps(
    clips
      .iter()
      .flat_map(|&(start, end)| [start, end])
      .collect::<Vec<_>>(),
  );
  let result = task.run(&vec![0.1; 96_000], &options).unwrap();

  assert_eq!(mock.counters().encode_calls(), 3, "one window per clip");
  let spans: Vec<(f32, f32)> = result
    .segments_slice()
    .iter()
    .map(|segment| (segment.start(), segment.end()))
    .collect();
  assert_eq!(spans.len(), 3, "one segment per clip, got {spans:?}");
  for (index, (&(start, end), &(clip_start, clip_end))) in spans.iter().zip(&clips).enumerate() {
    assert!(
      (start - clip_start).abs() < 1e-3,
      "segment {index} starts at its clip"
    );
    let expected_end = if index < 2 {
      clip_end
    } else {
      clip_start + 2.0
    };
    assert!(
      (end - expected_end).abs() < 1e-3,
      "segment {index} ends at {end}, expected {expected_end}"
    );
  }
  assert_eq!(result.text(), "Hello Hello Hello");
}

/// LAW (Codex R3, the default path): **a short clip on the default
/// options loses the words the padding holds.** The caller asks for no word
/// timings; the window its 0.4 s clip decodes is attributed by the word
/// timing all the same, for its clip-back alone. The model says
/// `<|0.00|> Hello world <|1.50|>`, its alignment placing "Hello" inside the
/// clip and "world" past it: the transcript is "Hello", the segment ends at
/// the clip, and it carries no words — the caller did not ask for them.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_short_clip_on_the_default_options_loses_the_words_the_padding_holds() {
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let world = t.encode(" world").unwrap()[0];
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  // Each step's row is 1.0 over the frames it is aligned to: "Hello" over
  // 0.06-0.5 s, "world" over 0.8-1.2 s — past the 0.4 s clip.
  let script: [(u32, core::ops::RangeInclusive<usize>); 8] = [
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(0), 2..=2),
    (hello, 3..=25),
    (world, 40..=60),
    (ts(75), 61..=65),
    (ts(75), 66..=66),
    (s.end_token(), 67..=67),
  ];
  for (token, frames) in script {
    let mut row = vec![0.0f32; 100];
    for frame in frames {
      row[frame] = 1.0;
    }
    mock.push_step_with_alignment(one_hot(token), row);
  }
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 6_400], &DecodingOptions::new())
    .unwrap();
  assert_eq!(result.text(), "Hello", "the padding's word is gone");
  assert_eq!(result.segments_slice().len(), 1);
  let segment = &result.segments_slice()[0];
  assert!(
    segment.end() <= 0.4 + 1e-4,
    "cut at the clip, got {}",
    segment.end()
  );
  assert!(
    segment.words_slice().is_empty(),
    "the caller asked for no words"
  );
}

/// LAW (Codex R3, no attribution): **a short clip whose window cannot be
/// attributed keeps no text past its last timestamp inside the clip.** The
/// model has no alignment output here, so nothing says which of
/// `<|0.00|> Hello <|2.00|>`'s words the 0.9 s clip holds: the segment runs
/// past the clip and its only timestamp inside is `<|0.00|>`, so its text
/// may all be padding — and none is emitted.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn an_unattributed_short_clip_keeps_no_text_past_its_last_timestamp_inside() {
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 14_400], &DecodingOptions::new())
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 1, "one window");
  assert_eq!(result.text(), "", "no text the padding may hold");
  assert!(result.segments_slice().is_empty());
}

/// LAW (Codex R4, the unclosed lump): **a short clip whose text no
/// timestamp inside it closes keeps none of that text, though its segment
/// ends at the clip.** The model says `<|0.00|> Hello <|endoftext|>`: no
/// timestamp pair, so the seeker lumps the window into one segment ending
/// at the window's end — the 0.9 s clip's own — and nothing attributes
/// "Hello" (the model has no alignment output). The segment does not run
/// past the clip, yet its text may all be padding, and none is emitted.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn an_unattributed_short_clip_keeps_no_text_that_no_timestamp_closes() {
  let t = tiny_tokenizer();
  let s = special();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  mock.push_token_steps(&[
    s.english_token(),
    s.transcribe_token(),
    ts(0),
    hello,
    s.end_token(),
  ]);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 14_400], &DecodingOptions::new())
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 1, "one window");
  assert_eq!(result.text(), "", "no text the padding may hold");
  assert!(result.segments_slice().is_empty());
}

/// Scripts one window: each step's token, its alignment row 1.0 over the
/// frames it is aligned to (20 ms each; the mock's `n_audio_ctx` must be
/// 100). A word's start is where the alignment leaves the token before
/// it, so a word meant to start past the clip follows one whose frames
/// reach past it.
fn script_aligned(mock: &mut MockBackend, script: &[(u32, core::ops::RangeInclusive<usize>)]) {
  for (token, frames) in script {
    let mut row = vec![0.0f32; 100];
    for frame in frames.clone() {
      row[frame] = 1.0;
    }
    mock.push_step_with_alignment(one_hot(*token), row);
  }
}

/// A 0.4 s clip's transcript on the default options, its window scripted.
fn short_clip_transcript(
  t: &WhisperTokenizer,
  script: &[(u32, core::ops::RangeInclusive<usize>)],
) -> String {
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  script_aligned(&mut mock, script);
  let task = TranscribeTask::new(&mock, t);
  task
    .run(&vec![0.1; 6_400], &DecodingOptions::new())
    .unwrap()
    .text()
    .to_owned()
}

/// LAW (Codex R5, [medium]): **a short clip keeps a word the visible
/// list's merge drops.** The model says `<|0.00|> Hello)] world <|1.50|>`
/// over a 0.4 s clip, its alignment placing `Hello`, `)` and `]` inside the
/// clip and `world` past it. Swift's merge folds `)` into `Hello)`, then
/// replaces that with `)]`, punctuation alone, which its final filter
/// removes — so the visible word list is `world` alone, the padding's, and
/// a clip-back reading it dropped the segment and `Hello` with it. The
/// clip-back reads the raw alignment: it cuts at `world` and keeps
/// `Hello)]`.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_short_clip_keeps_a_word_the_visible_merge_drops() {
  let t = tiny_tokenizer();
  let s = special();
  let token = |text: &str| t.encode(text).unwrap()[0];
  let text = short_clip_transcript(
    &t,
    &[
      (s.english_token(), 0..=0),
      (s.transcribe_token(), 1..=1),
      (ts(0), 2..=2),
      (token(" Hello"), 3..=10),
      (token(")"), 11..=12),
      (token("]"), 13..=25),
      (token(" world"), 40..=60),
      (ts(75), 61..=65),
      (ts(75), 66..=66),
      (s.end_token(), 67..=67),
    ],
  );
  assert_eq!(
    text, "Hello)]",
    "the padding's word is gone, the clip's kept"
  );
}

/// LAW (Codex R5, [medium]): **a padding word the visible list gives the
/// segment before it still leaves its own segment.** Two segments,
/// `<|0.00|> Hello!! <|0.20|>` and `<|0.20|> world <|0.30|>`, both inside
/// a 0.4 s clip by their timestamps; the alignment places `world` past the
/// clip. Swift's merge makes `!!` of the two `!`, two tokens for the three
/// `Hello!!` holds, so its word timing gives `world` to the first segment
/// and leaves the second wordless — where `<|0.30|>`, inside the clip, kept
/// `world`. The raw alignment gives `world` to the segment its token is
/// in: it lies in the padding, and the second segment goes.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_padding_word_the_visible_list_misplaces_still_leaves_its_own_segment() {
  let t = tiny_tokenizer();
  let s = special();
  let token = |text: &str| t.encode(text).unwrap()[0];
  let text = short_clip_transcript(
    &t,
    &[
      (s.english_token(), 0..=0),
      (s.transcribe_token(), 1..=1),
      (ts(0), 2..=2),
      (token(" Hello"), 3..=8),
      (token("!"), 9..=9),
      (token("!"), 10..=10),
      (ts(10), 11..=11),
      (ts(10), 12..=25),
      (token(" world"), 40..=60),
      (ts(15), 61..=65),
      (ts(15), 66..=66),
      (s.end_token(), 67..=67),
    ],
  );
  assert_eq!(text, "Hello!!", "the padding's word does not come back");
}

/// LAW (Codex R5, [medium]): **an inside word the visible list gives the
/// segment before it still keeps its own segment.** The same two segments,
/// the second `<|0.20|> world there <|0.30|>`: the alignment places `world`
/// inside the 0.4 s clip and `there` past it. Swift's word timing gives
/// `world` to the first segment, so the second's word list opens with
/// `there`, in the padding, and a clip-back reading it dropped the segment,
/// `world` with it. The raw alignment keeps `world` where its token is: the
/// second segment is cut at `there` and keeps `world`.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn an_inside_word_the_visible_list_misplaces_still_keeps_its_own_segment() {
  let t = tiny_tokenizer();
  let s = special();
  let token = |text: &str| t.encode(text).unwrap()[0];
  let text = short_clip_transcript(
    &t,
    &[
      (s.english_token(), 0..=0),
      (s.transcribe_token(), 1..=1),
      (ts(0), 2..=2),
      (token(" Hello"), 3..=6),
      (token("!"), 7..=7),
      (token("!"), 8..=8),
      (ts(10), 9..=9),
      (ts(10), 10..=10),
      (token(" world"), 11..=25),
      (token(" there"), 40..=60),
      (ts(15), 61..=65),
      (ts(15), 66..=66),
      (s.end_token(), 67..=67),
    ],
  );
  assert_eq!(text, "Hello!! world", "the inside word stays");
}

/// The transcript of a 0.4 s clip on `options`, its window scripted — the
/// prompt's own steps, if any, first.
fn short_clip_transcript_with(
  t: &WhisperTokenizer,
  options: &DecodingOptions,
  script: &[(u32, core::ops::RangeInclusive<usize>)],
) -> String {
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  script_aligned(&mut mock, script);
  let task = TranscribeTask::new(&mock, t);
  task
    .run(&vec![0.1; 6_400], options)
    .unwrap()
    .text()
    .to_owned()
}

/// LAW (Codex R6 row 1, [high]): **a window decoded behind a prompt
/// attributes its words as one decoded without.** A 0.4 s clip whose window
/// the model reads as `<|0.00|> Hello world <|1.50|>`, its alignment placing
/// `Hello` inside the clip and `world` past it, keeps `Hello`. Decoded behind
/// `prompt_tokens` — `<|startofprev|>` and two tokens before the
/// `<|startoftranscript|>`, three more decoder positions — the same window
/// keeps `Hello` too: each token reads the row its own decode committed at
/// its own position. Swift's prefix take read rows from the first, handing
/// `world` the row of a prompt-side token inside the clip.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_window_decoded_behind_a_prompt_attributes_its_words_as_one_without() {
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let world = t.encode(" world").unwrap()[0];
  let window: [(u32, core::ops::RangeInclusive<usize>); 8] = [
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(0), 2..=2),
    (hello, 3..=25),
    (world, 40..=60),
    (ts(75), 61..=65),
    (ts(75), 66..=66),
    (s.end_token(), 67..=67),
  ];
  let without = short_clip_transcript_with(&t, &DecodingOptions::new(), &window);
  assert_eq!(without, "Hello", "the padding's word is gone");

  let earlier = t.encode(" Earlier").unwrap()[0];
  let words = t.encode(" words").unwrap()[0];
  let prompted = DecodingOptions::new().with_prompt_tokens(vec![earlier, words]);
  // The prompt's own steps: the rows of `earlier`, `words` and the
  // `<|startoftranscript|>`, each inside the clip.
  let prompt_steps = [
    (earlier, 4..=6),
    (words, 7..=9),
    (s.start_of_transcript_token(), 10..=12),
  ];
  let behind =
    short_clip_transcript_with(&t, &prompted, &[&prompt_steps[..], &window[..]].concat());
  assert_eq!(
    behind, without,
    "behind a prompt, the same words are attributed"
  );
}

/// Each of `text`'s tokens with an even share of `frames`, in order — a
/// script's steps for the characters of one word.
fn spread(
  t: &WhisperTokenizer,
  text: &str,
  frames: core::ops::RangeInclusive<usize>,
) -> Vec<(u32, core::ops::RangeInclusive<usize>)> {
  let tokens = t.encode(text).unwrap();
  let (first, last) = (*frames.start(), *frames.end());
  let share = (last + 1 - first) / tokens.len();
  tokens
    .iter()
    .enumerate()
    .map(|(index, &token)| {
      let from = first + index * share;
      let to = if index + 1 == tokens.len() {
        last
      } else {
        from + share - 1
      };
      (token, from..=to)
    })
    .collect()
}

/// LAW (Codex R8 row 2, [medium]): **a phrase the clip cut keeps a word
/// weighed by the tokens it kept.** A 0.4 s Chinese clip with word timings
/// asked for, the model reading `<|0.00|>中文幻觉<|1.50|>`, 幻 and 觉 past
/// the clip. The default grouping makes one word of the phrase, opening at
/// the timestamp; the clip keeps `<|0.00|>中文`, and the visible word `中文`
/// is weighed by those three tokens' mean log probability — not by all
/// five, two of them removed — and ends inside the segment.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_phrase_the_clip_cut_keeps_a_word_weighed_by_the_tokens_it_kept() {
  let t = tiny_tokenizer();
  let s = special();
  let mut script = vec![
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(0), 2..=2),
  ];
  script.extend(spread(&t, "中", 3..=8));
  script.extend(spread(&t, "文", 9..=25));
  script.extend(spread(&t, "幻", 40..=48));
  script.extend(spread(&t, "觉", 49..=60));
  script.extend([
    (ts(75), 61..=65),
    (ts(75), 66..=66),
    (s.end_token(), 67..=67),
  ]);
  let (segments, words) = short_clip_words(
    &t,
    &DecodingOptions::new()
      .with_language("zh")
      .with_word_timestamps(),
    &script,
  );
  assert_eq!(words, [["中文"]], "the kept part of the phrase");
  let segment = &segments[0];
  let kept: Vec<u32> = [&[ts(0)][..], &t.encode("中文").unwrap()].concat();
  let logged: Vec<f32> = segment
    .token_log_probs_slice()
    .iter()
    .skip_while(|&&(token, _)| token != ts(0))
    .take(kept.len())
    .map(|&(_, log_prob)| log_prob)
    .collect();
  assert_eq!(logged.len(), kept.len(), "{segment:?}");
  let own = (logged.iter().sum::<f32>() / logged.len() as f32).exp();
  let word = &segment.words_slice()[0];
  assert!(
    (word.probability() - (own * 100.0).round() / 100.0).abs() < 1e-6,
    "weighed by its own {} tokens: {} for {own}",
    kept.len(),
    word.probability()
  );
  assert!(
    word.end() <= segment.end(),
    "it ends inside its segment: {word:?} in {segment:?}"
  );
}

/// LAW (Codex R9 row 2, [medium]): **a word grouped with a timestamp the
/// clip-back restated is weighed by its own text.** A 0.4 s Chinese clip with
/// word timings asked for, the model reading `<|0.50|>中文<|0.80|>`, its
/// alignment placing 中文 inside the clip: the segment's own bounds lie in
/// the padding, so it takes them from its raw words, and its first
/// timestamp is restated at the step its text starts at. The default
/// grouping makes one word of `<|0.50|>中文`, from the timestamp on; the
/// visible word `中文` is weighed by 中 and 文 alone — the restated step
/// logged `<|0.50|>`, which the segment no longer holds — never by the
/// aligned word's probability, which weighed that timestamp too.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_word_grouped_with_a_restated_timestamp_is_weighed_by_its_own_text() {
  let t = tiny_tokenizer();
  let s = special();
  let mut script = vec![
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(25), 2..=2),
  ];
  script.extend(spread(&t, "中文", 3..=14));
  script.extend([
    (ts(40), 15..=17),
    (ts(40), 18..=18),
    (s.end_token(), 19..=19),
  ]);
  let (segments, words) = short_clip_words(
    &t,
    &DecodingOptions::new()
      .with_language("zh")
      .with_word_timestamps(),
    &script,
  );
  assert_eq!(words, [["中文"]], "the segment and its word kept");
  let segment = &segments[0];
  let text = t.encode("中文").unwrap();
  let pairs = segment.token_log_probs_slice();
  // The step the model sampled `<|0.50|>` at keeps that pair.
  let at = pairs
    .iter()
    .position(|&(token, _)| token == ts(25))
    .expect("the sampled timestamp's pair");
  assert!(
    segment.tokens_slice()[at] != ts(25) && segment.tokens_slice()[at] >= ts(0),
    "its first timestamp restated: {segment:?}"
  );
  assert_eq!(
    &segment.tokens_slice()[at + 1..=at + text.len()],
    text.as_slice(),
    "{segment:?}"
  );
  let sampled: Vec<f32> = pairs[at + 1..=at + text.len()]
    .iter()
    .map(|&(_, log_prob)| log_prob)
    .collect();
  let mean = |log_probs: &[f32]| log_probs.iter().sum::<f32>() / log_probs.len() as f32;
  let rounded = |probability: f32| (probability * 100.0).round() / 100.0;
  let own = rounded(mean(&sampled).exp());
  let with_the_timestamp = rounded(mean(&[&[pairs[at].1][..], &sampled].concat()).exp());
  assert_ne!(
    own, with_the_timestamp,
    "the timestamp's log probability tells the two apart"
  );
  let word = &segment.words_slice()[0];
  assert!(
    (word.probability() - own).abs() < 1e-6,
    "weighed by 中 and 文 alone: {} for {own} (with the timestamp {with_the_timestamp})",
    word.probability()
  );
}

/// LAW (Codex R9 row 3, [medium]): **a segment whose timestamps run
/// backwards is retimed from the raw words it kept, never handed on out of
/// order.** A 0.4 s clip decoded `without_timestamps`, which filters no
/// timestamp order, the backend reading `<|0.30|> Hello <|0.10|><|0.10|>`:
/// the seeker's first segment spans 0.30 to 0.10, and the alignment places
/// `Hello` inside the clip. The clip-back keeps it and retimes the segment
/// from the raw word, so its start precedes its end; with word timings
/// asked for, its word is held inside those bounds — where the bare clamp,
/// handed 0.30 to 0.10, panicked — and without them the segment is the
/// same.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_segment_whose_timestamps_run_backwards_is_retimed_from_its_raw_words() {
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let script = [
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (s.no_timestamps_token(), 2..=2),
    (ts(15), 3..=3),
    (hello, 4..=9),
    (ts(5), 10..=10),
    (ts(5), 11..=11),
    (s.end_token(), 12..=12),
  ];
  let (segments, words) = short_clip_words(
    &t,
    &DecodingOptions::new()
      .with_without_timestamps()
      .with_word_timestamps(),
    &script,
  );
  let bounds: Vec<(f32, f32)> = segments
    .iter()
    .map(|segment| (segment.start(), segment.end()))
    .collect();
  assert_eq!(
    words,
    [[" Hello"]],
    "the text kept, its word with it: {bounds:?}"
  );
  let (start, end) = bounds[0];
  assert!(
    start < end && end <= 0.4,
    "retimed in order, inside the clip: {bounds:?}"
  );
  let word = &segments[0].words_slice()[0];
  assert!(
    start <= word.start() && word.start() <= word.end() && word.end() <= end,
    "its word held inside its bounds: {word:?} in {bounds:?}"
  );
  let (plain, _) = short_clip_words(
    &t,
    &DecodingOptions::new().with_without_timestamps(),
    &script,
  );
  let plain_bounds: Vec<(f32, f32)> = plain
    .iter()
    .map(|segment| (segment.start(), segment.end()))
    .collect();
  assert_eq!(
    plain_bounds, bounds,
    "the same segment with word timings or without"
  );
}

/// LAW (Codex R10, [medium]): **every alignment pass is recorded once, its
/// time with it.** `record_alignment_pass` runs one pass and adds its
/// elapsed time to `decoding_word_timestamps` and one run to
/// `total_timestamp_alignment_runs`; two passes add both times and two runs.
#[test]
fn an_alignment_pass_is_recorded_with_its_time() {
  let mut timings = crate::audio::whisper::result::TranscriptionTimings::new();
  let pause = core::time::Duration::from_millis(5);
  let answer = super::record_alignment_pass(&mut timings, || {
    std::thread::sleep(pause);
    7
  });
  assert_eq!(answer, 7, "the pass's own answer");
  assert_eq!(timings.total_timestamp_alignment_runs(), 1.0, "one run");
  let first = timings.decoding_word_timestamps();
  assert!(first >= pause.as_secs_f64(), "its time: {first}");
  super::record_alignment_pass(&mut timings, || std::thread::sleep(pause));
  assert_eq!(timings.total_timestamp_alignment_runs(), 2.0, "two runs");
  assert!(
    timings.decoding_word_timestamps() >= first + pause.as_secs_f64(),
    "both times: {}",
    timings.decoding_word_timestamps()
  );
}

/// LAW (Codex R10, [medium]): **a short clip's visible words are an
/// alignment pass of their own, recorded.** A 0.4 s clip whose window the
/// model reads as `<|0.00|> Hello!! <|0.20|>` and `<|0.20|> world there
/// <|0.30|>`, its text surviving the clip-back. On the default options the
/// clip-back's raw attribution is the window's one alignment pass: one run.
/// With word timings the window is aligned again for the visible words
/// after the clip-back: two runs, and `decoding_word_timestamps` holds the
/// time of both. The second pass went unrecorded: one run for two passes,
/// its time missing.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_short_clips_visible_words_are_an_alignment_pass_of_their_own() {
  let t = tiny_tokenizer();
  let script = hello_world_there(&t);
  let run = |options: &DecodingOptions| {
    let mut mock = MockBackend::new().with_dims(
      ModelDims::new()
        .with_window_samples(16_000)
        .with_n_audio_ctx(100),
    );
    script_aligned(&mut mock, &script);
    TranscribeTask::new(&mock, &t)
      .run(&vec![0.1; 6_400], options)
      .unwrap()
  };
  let plain = run(&DecodingOptions::new());
  let worded = run(&DecodingOptions::new().with_word_timestamps());
  assert!(
    !worded.segments_slice().is_empty()
      && worded
        .segments_slice()
        .iter()
        .any(|segment| !segment.words_slice().is_empty()),
    "the clip keeps its text, and its words"
  );
  assert_eq!(
    plain.timings().total_timestamp_alignment_runs(),
    1.0,
    "the clip-back's attribution alone"
  );
  assert_eq!(
    worded.timings().total_timestamp_alignment_runs(),
    2.0,
    "the attribution, then the visible words' own alignment"
  );
  assert!(
    worded.timings().decoding_word_timestamps() > 0.0,
    "their time recorded"
  );
}

/// LAW (Codex R8 row 3, [medium]): **one zero-duration policy, the
/// clip-back's, whatever the caller asked for.** A 0.4 s clip whose window
/// the model reads as `<|0.50|> hi <|0.90|>`, its bounds wholly in the
/// padding, the alignment squeezing `hi` to no length exactly at the clip's
/// end: it holds none of the padding, so the clip-back keeps it, and the
/// segment takes its bounds from it, 0.40 to 0.40. Decoded with word timings
/// and without, the transcript and the segments are the same — the
/// zero-length filter that ran after the derived words dropped the segment
/// only when word timings were asked for.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_squeezed_word_at_the_clip_end_is_kept_with_word_timings_or_without() {
  let t = tiny_tokenizer();
  let s = special();
  let hi = t.encode(" hi").unwrap()[0];
  // A row of the mock's 100 frames: `value` over each range, `rest` elsewhere.
  let row = |frames: &[(core::ops::RangeInclusive<usize>, f32)], rest: f32| {
    let mut row = vec![rest; 100];
    for (range, value) in frames {
      for frame in range.clone() {
        row[frame] = *value;
      }
    }
    row
  };
  let steps: Vec<(u32, Vec<f32>)> = vec![
    (s.english_token(), row(&[(0..=0, 1.0)], 0.0)),
    (s.transcribe_token(), row(&[(1..=1, 1.0)], 0.0)),
    // The opening timestamp up to the clip's last frame, and nowhere else:
    // the path leaves it there with no tie to break.
    (ts(25), row(&[(2..=19, 1.0)], -10.0)),
    // `hi`: nowhere but the clip's end, where the path passes through it.
    (hi, row(&[(20..=20, 0.5)], -10.0)),
    (ts(45), row(&[(20..=40, 1.0)], 0.0)),
    (ts(45), row(&[(41..=41, 1.0)], 0.0)),
    (s.end_token(), row(&[(42..=42, 1.0)], 0.0)),
  ];
  let run = |options: &DecodingOptions| {
    let mut mock = MockBackend::new().with_dims(
      ModelDims::new()
        .with_window_samples(16_000)
        .with_n_audio_ctx(100),
    );
    for (token, row) in &steps {
      mock.push_step_with_alignment(one_hot(*token), row.clone());
    }
    let result = TranscribeTask::new(&mock, &t)
      .run(&vec![0.1; 6_400], options)
      .unwrap();
    let segments: Vec<(String, f32, f32)> = result
      .segments_slice()
      .iter()
      .map(|segment| (segment.text().to_owned(), segment.start(), segment.end()))
      .collect();
    (result.text().to_owned(), segments)
  };
  let without = run(&DecodingOptions::new());
  assert_eq!(without.0, "hi", "the squeezed word is kept: {without:?}");
  assert!(
    without.1.iter().all(|(_, start, end)| start == end),
    "its segment has no length: {without:?}"
  );
  let with = run(&DecodingOptions::new().with_word_timestamps());
  assert_eq!(
    with, without,
    "the same transcript and segments with word timings"
  );
}

/// LAW (Codex R6 row 2, [high]): **no special token starts, ends or cuts a
/// textual raw word.** A 0.4 s Chinese clip on the default options, the
/// model reading `<|0.00|>中文幻觉<|1.50|>`, its alignment placing 中 and 文
/// inside the clip and 幻 and 觉 past it. The default grouping for Chinese is
/// Swift's space splitter, which starts a word at `<|0.00|>` and appends every
/// character after it: a raw word that started inside the clip and was read
/// as crossing its end, every padding character kept. The raw words are the
/// text alone, each character its own unit timed by its own tokens: 幻 and 觉
/// lie in the padding and go — exactly them.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn no_special_token_starts_ends_or_cuts_a_textual_raw_word() {
  let t = tiny_tokenizer();
  let s = special();
  let mut script = vec![
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(0), 2..=2),
  ];
  script.extend(spread(&t, "中", 3..=8));
  script.extend(spread(&t, "文", 9..=25));
  script.extend(spread(&t, "幻", 40..=48));
  script.extend(spread(&t, "觉", 49..=60));
  script.extend([
    (ts(75), 61..=65),
    (ts(75), 66..=66),
    (s.end_token(), 67..=67),
  ]);
  let text = short_clip_transcript_with(&t, &DecodingOptions::new().with_language("zh"), &script);
  assert_eq!(
    text, "中文",
    "the characters the padding holds go, exactly them"
  );
}

/// The two segments `<|0.00|> Hello!! <|0.20|>` and `<|0.20|> world there
/// <|0.30|>` over a 0.4 s clip, the alignment placing `world` inside the clip
/// and `there` past it.
fn hello_world_there(t: &WhisperTokenizer) -> Vec<(u32, core::ops::RangeInclusive<usize>)> {
  let s = special();
  let token = |text: &str| t.encode(text).unwrap()[0];
  vec![
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(0), 2..=2),
    (token(" Hello"), 3..=6),
    (token("!"), 7..=7),
    (token("!"), 8..=8),
    (ts(10), 9..=9),
    (ts(10), 10..=10),
    (token(" world"), 11..=25),
    (token(" there"), 40..=60),
    (ts(15), 61..=65),
    (ts(15), 66..=66),
    (s.end_token(), 67..=67),
  ]
}

/// LAW (Codex R6 row 3, [medium]): **no segment is rejected on bounds the
/// visible words gave it.** With word timings asked for, the visible word
/// list's merge makes `!!` of the two `!` — two tokens for the three
/// `Hello!!` holds — so its word timing gives `world` to the first segment,
/// and the second segment is re-timed from `there`, in the padding. A
/// clip-back that rejected a segment whose bounds lie in the padding dropped
/// the second segment, `world` with it. What survives decides: the raw
/// alignment keeps `world` inside the clip, and the second segment stays.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn no_segment_is_rejected_on_bounds_the_visible_words_gave_it() {
  let t = tiny_tokenizer();
  let text = short_clip_transcript_with(
    &t,
    &DecodingOptions::new().with_word_timestamps(),
    &hello_world_there(&t),
  );
  assert_eq!(text, "Hello!! world", "the inside word stays");
}

/// LAW (Codex R6 row 4, [medium]): **the visible words are derived from
/// the raw words the clip-back kept, and hold no token it removed.** With
/// word timings asked for, a 0.4 s clip whose window the model reads as
/// `<|0.00|> A. <|1.00|>`: the alignment places `A` from inside the clip and
/// the period wholly in the padding. The raw cut removes the period from the
/// tokens and the text. A visible list filtered apart from them, by its own
/// timings, kept the merged `A.` — `A`'s timing — so words and text
/// disagreed, and a prefix built from the words (Local Agreement's) carried
/// the clipped period into the next decode. Derived from what survived, the
/// visible words are `A` alone, and every token of every word is one its
/// segment kept.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn the_visible_words_are_derived_from_what_the_clip_back_kept() {
  let t = tiny_tokenizer();
  let s = special();
  let a = t.encode(" A").unwrap()[0];
  let period = t.encode(".").unwrap()[0];
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  script_aligned(
    &mut mock,
    &[
      (s.english_token(), 0..=0),
      (s.transcribe_token(), 1..=1),
      (ts(0), 2..=2),
      (a, 3..=22),
      (period, 30..=40),
      (ts(50), 41..=45),
      (ts(50), 46..=46),
      (s.end_token(), 47..=47),
    ],
  );
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(
      &vec![0.1; 6_400],
      &DecodingOptions::new().with_word_timestamps(),
    )
    .unwrap();
  assert_eq!(result.text(), "A", "the padding's period is cut");
  let words: Vec<(String, Vec<u32>)> = result
    .segments_slice()
    .iter()
    .flat_map(|segment| {
      segment
        .words_slice()
        .iter()
        .map(|word| (word.word().to_owned(), word.tokens_slice().to_vec()))
    })
    .collect();
  assert_eq!(
    words,
    [(" A".to_owned(), vec![a])],
    "the visible words are the kept text's"
  );
  for segment in result.segments_slice() {
    for word in segment.words_slice() {
      assert!(
        word
          .tokens_slice()
          .iter()
          .all(|token| segment.tokens_slice().contains(token)),
        "a word holds only tokens its segment kept: {words:?}"
      );
    }
  }
}

/// The visible words of each segment a 0.4 s clip's window keeps, on
/// `options`, its window scripted — beside the segments themselves.
fn short_clip_words(
  t: &WhisperTokenizer,
  options: &DecodingOptions,
  script: &[(u32, core::ops::RangeInclusive<usize>)],
) -> (Vec<TranscriptionSegment>, Vec<Vec<String>>) {
  clip_words(t, options, script, 6_400)
}

/// The visible words of each segment a clip of `samples` keeps, on
/// `options`, its one window scripted — beside the segments themselves.
fn clip_words(
  t: &WhisperTokenizer,
  options: &DecodingOptions,
  script: &[(u32, core::ops::RangeInclusive<usize>)],
  samples: usize,
) -> (Vec<TranscriptionSegment>, Vec<Vec<String>>) {
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  script_aligned(&mut mock, script);
  let result = TranscribeTask::new(&mock, t)
    .run(&vec![0.1; samples], options)
    .unwrap();
  let segments = result.segments_slice().to_vec();
  let words = segments
    .iter()
    .map(|segment| {
      segment
        .words_slice()
        .iter()
        .map(|word| word.word().to_owned())
        .collect()
    })
    .collect();
  (segments, words)
}

/// LAW (Codex R7 row 2, [medium]): **each segment's visible words are
/// derived from its own words alone.** With word timings asked for, the two
/// segments `<|0.00|> Hello!! <|0.20|>` and `<|0.20|> world there <|0.30|>`
/// over a 0.4 s clip, `there` in the padding. A derivation over every
/// segment's words at once merged the two `!` into `!!` — two tokens for the
/// three `Hello!!` holds — so the word-timing pass's token budget gave the
/// first segment `world` too, a word whose token it does not hold, and left
/// the second wordless. Derived per segment, `world` stays in its own, and
/// every word holds only tokens of its segment.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn each_segment_derives_its_visible_words_from_its_own_words() {
  let t = tiny_tokenizer();
  let (segments, words) = short_clip_words(
    &t,
    &DecodingOptions::new().with_word_timestamps(),
    &hello_world_there(&t),
  );
  assert_eq!(words.len(), 2, "both segments kept: {words:?}");
  assert_eq!(
    words[1],
    [" world"],
    "the second segment keeps its own word: {words:?}"
  );
  for segment in &segments {
    for word in segment.words_slice() {
      assert!(
        word
          .tokens_slice()
          .iter()
          .all(|token| segment.tokens_slice().contains(token)),
        "a word holds only tokens of its segment: {words:?}"
      );
    }
  }
}

/// A visible word's text and times.
type TimedWord = (String, f32, f32);

/// The visible words of a clip of `samples`, on `options`, its one window
/// scripted: each word's text and times, segment by segment, beside the
/// segments' bounds.
fn timed_words(
  t: &WhisperTokenizer,
  options: &DecodingOptions,
  script: &[(u32, core::ops::RangeInclusive<usize>)],
  samples: usize,
) -> (Vec<(f32, f32)>, Vec<Vec<TimedWord>>) {
  let (segments, _) = clip_words(t, options, script, samples);
  let bounds = segments
    .iter()
    .map(|segment| (segment.start(), segment.end()))
    .collect();
  let words = segments
    .iter()
    .map(|segment| {
      segment
        .words_slice()
        .iter()
        .map(|word| (word.word().to_owned(), word.start(), word.end()))
        .collect()
    })
    .collect();
  (bounds, words)
}

/// LAW (Codex R7 row 3, [medium]): **a clipped window's visible words are
/// grouped and gathered as the caller asked, as a window that is not.** A
/// Chinese window, `<|0.00|>中文字幕<|0.30|>`, its alignment placing every
/// character inside the first 0.4 s, on `AlignmentGather::SwiftParity` and
/// the default grouping — Swift's space splitter, which makes one word of
/// the four. Decoded as a 1.2 s clip, the window is not clipped and its
/// words come from that pass; decoded as a 0.4 s clip, its clip-back
/// removes nothing and keeps the segment's own bounds, and its visible
/// words are the same words, timed the same, held inside those bounds. The
/// fine-grained units the clip-back attributes by are for clipping alone:
/// visible words made of them were characters on a short clip, phrases on
/// a long one, and their timing bypassed the caller's gather — which, where
/// CoreVideo pads a row (128 elements for these 100 columns on the
/// reference host), cuts the last character's row short and ends the word
/// at 0.22 s, where the complete gather ends it at 0.28 s.
#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_clipped_window_groups_its_visible_words_as_the_caller_asked() {
  let t = tiny_tokenizer();
  let s = special();
  let mut script = vec![
    (s.english_token(), 0..=0),
    (s.transcribe_token(), 1..=1),
    (ts(0), 2..=2),
  ];
  script.extend(spread(&t, "中文字幕", 3..=14));
  script.extend([
    (ts(15), 15..=17),
    (ts(15), 18..=18),
    (s.end_token(), 19..=19),
  ]);
  let options = DecodingOptions::new()
    .with_language("zh")
    .with_word_timestamps()
    .with_alignment_gather(AlignmentGather::SwiftParity);
  let (unclipped_bounds, unclipped) = timed_words(&t, &options, &script, 19_200);
  let (clipped_bounds, clipped) = timed_words(&t, &options, &script, 6_400);
  let texts = |words: &[Vec<TimedWord>]| {
    words
      .iter()
      .map(|segment| {
        segment
          .iter()
          .map(|(word, _, _)| word.clone())
          .collect::<Vec<_>>()
      })
      .collect::<Vec<_>>()
  };
  assert_eq!(
    texts(&unclipped),
    [["中文字幕"]],
    "the caller's grouping: one word from the timestamp on"
  );
  assert_eq!(
    texts(&clipped),
    texts(&unclipped),
    "the clipped window groups as the window that is not"
  );
  assert_eq!(
    clipped_bounds.len(),
    1,
    "one segment: {clipped_bounds:?} (unclipped {unclipped_bounds:?})"
  );
  let (start, end) = clipped_bounds[0];
  assert!(
    start == 0.0 && (end - 0.3).abs() < 1e-6,
    "its own bounds, <|0.00|> to <|0.30|>: {clipped_bounds:?}"
  );
  let held: Vec<Vec<TimedWord>> = unclipped
    .iter()
    .map(|segment| {
      segment
        .iter()
        .map(|(word, from, to)| (word.clone(), from.clamp(start, end), to.clamp(start, end)))
        .collect()
    })
    .collect();
  assert_eq!(
    clipped, held,
    "timed as the window that is not, through the caller's gather, held in its bounds"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn zero_window_run_observes_no_language_in_provenance() {
  // F3 (codex round 2), end to end. A run over no audio decodes NO window
  // (encode_calls == 0), so the pipeline observes no language. The result
  // still carries the Swift-compat `"en"` DISPLAY fallback, but the recorded
  // observation -- and therefore `Provenance::for_result` -- must be `None`,
  // not a fabricated language the pipeline never saw.
  let t = tiny_tokenizer();
  let mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let task = TranscribeTask::new(&mock, &t);
  let result = task.run(&[], &DecodingOptions::new()).unwrap();

  assert_eq!(mock.counters().encode_calls(), 0, "no window decoded");
  assert_eq!(result.language(), "en", "the display fallback is kept");
  assert_eq!(
    result.task_facts().observed_language(),
    None,
    "nothing was observed, so the result records no detected language"
  );

  // F3 (codex round 8). A zero-window run POSITIVELY knows it drew nothing and
  // was truncated by nothing: no window decoded, so no attempt could draw or be
  // stopped. Seeding the fact sink OBSERVED-CLEAN (not `unknown()`) records the
  // honest `Some(false)`/`Some(false)`, so the run is reproducible -- where the
  // pre-fix `unknown()` seed left it conservatively non-reproducible.
  //
  // Mutation proof: revert the sink seed to `TaskFacts::unknown()` and both
  // booleans read back `None`, failing `is_reproducible()` below.
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(false),
    "a run that decoded no window POSITIVELY drew nothing"
  );
  assert_eq!(
    result.task_facts().early_stopped(),
    Some(false),
    "and was truncated by nothing"
  );

  let provenance = crate::audio::whisper::provenance::Provenance::for_result(
    &DecodingOptions::new(),
    &crate::audio::whisper::options::ComputeOptions::new(),
    &result,
  );
  assert_eq!(
    provenance.task_facts().observed_language(),
    None,
    "and neither does the provenance -- absent, not fabricated"
  );
  assert!(
    provenance.is_reproducible(),
    "an honest zero-window run reproduces byte-for-byte -- it did nothing to redo"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn single_window_run_produces_segments_and_text() {
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let task = TranscribeTask::new(&mock, &t);
  // 2 s of audio, 1 s mock windows (window_samples 16_000): window at seek 0
  // runs (0 < 32000 - 16000); its <|2.00|> ending advances seek to 32000,
  // which fails the guard -> exactly one window.
  let result = task
    .run(&vec![0.1; 32_000], &DecodingOptions::new())
    .unwrap();
  assert_eq!(result.text(), "Hello"); // decoded word tokens, trimmed (TranscribeTask.swift:304-305)
  assert_eq!(result.segments_slice().len(), 1);
  let segment = &result.segments_slice()[0];
  assert!((segment.start() - 0.0).abs() < 1e-4);
  assert!((segment.end() - 2.0).abs() < 1e-4);
  assert_eq!(mock.counters().resets(), 1, "state reset after the window");
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn windowing_advances_seek_by_last_timestamp_and_decodes_again() {
  let t = tiny_tokenizer();
  // 3 s of audio with 1 s windows: the scripted window ends with a
  // <|1.00|> pair -> seek advances 1 s per window; the state reset between
  // windows rewinds the mock's script cursor (it lives in the state), so
  // one scripted window replays for every window.
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  let s = special();
  mock.push_token_steps(&[
    s.english_token(),
    s.transcribe_token(),
    ts(0),
    hello,
    ts(50), // <|1.00|>
    ts(50),
    s.end_token(),
  ]);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 48_000], &DecodingOptions::new())
    .unwrap();
  // window 0 covers [0, 16000) -> seek 16000; window 1 -> seek 32000;
  // guard: 32000 < 48000 - 16000 is false -> stop.
  assert_eq!(result.segments_slice().len(), 2);
  assert!(
    (result.segments_slice()[1].start() - 1.0).abs() < 1e-4,
    "time offset applied"
  );
  assert_eq!(mock.counters().encode_calls(), 2);
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn fallback_ladder_retries_with_rising_temperature_then_accepts() {
  let t = tiny_tokenizer();
  let s = special();
  // A window whose avg logprob is catastrophically low. without_timestamps
  // keeps TimestampRulesFilter out (near-flat logits would otherwise trip
  // its sum-vs-max forcing) and makes the seeker take the lump branch with
  // a FULL segment_size seek advance — guaranteed loop progress.
  // Per-attempt script (prompt [SOT, en, transcribe, <|notimestamps|>]):
  // 3 forced-prompt predictions + 1 sampled step + EOT = 5 steps.
  // The sampled step's logits are flat-with-EOT-pinned-low: every candidate
  // equally (un)likely at lp = ln(1/51864) ~ -10.86, and EOT can never land
  // in the top-k -> deterministic step COUNTS at any temperature.
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  for _ in 0..3 {
    for _ in 0..4 {
      let mut flat = vec![0.0f32; 51865];
      flat[s.end_token() as usize] = -20.0;
      mock.push_step(flat);
    }
    mock.push_token_step(s.end_token());
  }
  // avg logprob over SOT..=EOT: (4 prompt zeros + -10.86 + EOT 0)/6 ~ -1.81
  // < -1.0 default -> LogProbThreshold fallback on EVERY attempt; the
  // ladder exhausts and the final attempt's result stands
  // (TranscribeTask.swift:394-410).
  let options = DecodingOptions::new()
    .with_without_timestamps()
    .maybe_first_token_logprob_threshold(None)
    .maybe_compression_ratio_threshold(None)
    .with_temperature_fallback_count(2); // 3 attempts total
  let task = TranscribeTask::new(&mock, &t);
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  let counters = mock.counters();
  // Swift resets on every needsFallback, INCLUDING the exhausted final
  // attempt (TranscribeTask.swift:394-404), plus the per-window reset:
  assert_eq!(
    counters.resets(),
    3 + 1,
    "3 fallback resets + 1 window reset"
  );
  assert_eq!(
    result.segments_slice().len(),
    1,
    "lump branch: one full-window segment"
  );
  assert!(
    (result.segments_slice()[0].temperature() - 0.4).abs() < 1e-3,
    "final attempt at temperature 0.0 + 2 * 0.2"
  );
}

/// Scripts the exact catastrophic-avg-logprob window
/// `fallback_ladder_retries_with_rising_temperature_then_accepts` uses to
/// force the fallback ladder to exhaust all 3 attempts regardless of
/// temperature (see that test's own comments for the avg-logprob
/// derivation). Reused here because it is a PROVEN fallback-forcing
/// script, and because its 4 "flat" (all-zero-but-EOT) steps per attempt
/// are genuine top-k multinomial draws at temperature > 0: the sampled
/// TOKEN is RNG-dependent even though the STEP COUNT is not, which is
/// exactly the observable coremlit issue #9's seed-reproducibility
/// contract needs.
fn script_exhausting_fallback_window(mock: &mut MockBackend, end_token: u32) {
  for _ in 0..3 {
    for _ in 0..4 {
      let mut flat = vec![0.0f32; 51865];
      flat[end_token as usize] = -20.0;
      mock.push_step(flat);
    }
    mock.push_token_step(end_token);
  }
}

/// The fallback-exhausting options recipe, with a nonzero base
/// `temperature` (so even ATTEMPT 0 draws from the RNG — attempt 0 at the
/// crate's default `temperature() == 0.0` would sample by argmax alone,
/// never touching the seed) and `seed` set from the given value.
fn exhausting_fallback_options(seed: Option<u64>) -> DecodingOptions {
  DecodingOptions::new()
    .with_temperature(0.3)
    .with_without_timestamps()
    .maybe_first_token_logprob_threshold(None)
    .maybe_compression_ratio_threshold(None)
    .with_temperature_fallback_count(2) // 3 attempts total
    .maybe_seed(seed)
}

/// Runs the exhausting-fallback scenario end to end against a freshly
/// built [`MockBackend`]/[`TranscribeTask`] pair, so repeated calls are
/// fully independent runs (no shared mutable state whatsoever) — the
/// same shape a real caller re-invoking [`WhisperKit::transcribe`] twice
/// would see.
fn run_exhausting_fallback(t: &WhisperTokenizer, seed: Option<u64>) -> TranscriptionResult {
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_exhausting_fallback_window(&mut mock, special().end_token());
  let task = TranscribeTask::new(&mock, t);
  let audio = vec![0.1f32; 32_000];
  task
    .run(&audio, &exhausting_fallback_options(seed))
    .unwrap()
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn seeded_fallback_ladder_is_bit_reproducible_across_runs() {
  // Closes coremlit issue #9's final open item: with a seed set, the
  // fallback ladder can stay fully enabled AND be bit-reproducible.
  // N (here 4) entirely independent runs (fresh backend/task every time)
  // at the same seed, each forcing the SAME 3-attempt exhausting ladder,
  // must all sample byte-identical tokens.
  let t = tiny_tokenizer();
  let runs: Vec<TranscriptionResult> = (0..4)
    .map(|_| run_exhausting_fallback(&t, Some(7)))
    .collect();
  let reference = &runs[0];
  assert_eq!(reference.segments_slice().len(), 1);
  let reference_tokens = reference.segments_slice()[0].tokens_slice();
  for (index, run) in runs.iter().enumerate().skip(1) {
    assert_eq!(run.segments_slice().len(), 1);
    assert_eq!(
      run.segments_slice()[0].tokens_slice(),
      reference_tokens,
      "run {index} diverged from run 0: same seed, same fallback ladder -> byte-identical sampled tokens"
    );
    assert_eq!(run.text(), reference.text(), "run {index} text diverged");
  }
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn seeded_fallback_ladder_differs_across_seeds() {
  // Proves the seed is actually threaded into the pipeline's sampler
  // construction, not silently ignored: a DIFFERENT base seed over the
  // identical scripted scenario must sample different tokens. (If this
  // ever flakes because two specific seed literals happen to coincide,
  // that is a signal to pick different literals, not to delete the
  // property -- verified empirically for the literals below before
  // trusting them.)
  let t = tiny_tokenizer();
  let a = run_exhausting_fallback(&t, Some(7));
  let b = run_exhausting_fallback(&t, Some(99));
  assert_ne!(
    a.segments_slice()[0].tokens_slice(),
    b.segments_slice()[0].tokens_slice(),
    "different seeds must not sample the same tokens"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn unseeded_fallback_ladder_still_runs_without_threading_a_seed() {
  // `seed = None` (the default): the fallback ladder must still run to
  // completion exactly as it did before this knob existed. Deliberately
  // NOT asserting any determinism/nondeterminism property here (an
  // OS-seeded run could coincidentally repeat) -- only that this code
  // path is exercised successfully. `options.seed()` returning `None`
  // means `decode_with_fallback`'s `if let Some(seed) = ...` body never
  // runs, so no seed is threaded into the sampler at all; that skip is a
  // structural (code-path) guarantee, not something this test can
  // observe from the outside without breaking the "don't assert
  // (non)determinism" rule above.
  let t = tiny_tokenizer();
  let result = run_exhausting_fallback(&t, None);
  assert_eq!(result.segments_slice().len(), 1, "lump branch, as scripted");
  assert!(
    (result.segments_slice()[0].temperature() - (0.3 + 2.0 * 0.2)).abs() < 1e-3,
    "ladder still exhausts to the final (highest-temperature) attempt"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn compression_failure_marks_swallowed_error() {
  // F2 (codex round 14). Foundation's zlib error is erased with `.ok()`
  // (`text::zlib_compressed_len`) and becomes a `+inf` compression ratio, which
  // drives a temperature fallback to a DIFFERENT (higher-temperature) attempt --
  // yet `had_swallowed_error` stayed `Some(false)` (only the language-probe
  // swallow set it), so `is_reproducible` trusted a run whose hidden OS error a
  // re-run may not repeat. The fix routes every compression through a
  // thread-local swallow flag the fallback ladder reads per attempt, so an
  // erased error that controlled the transcript is recorded honestly.
  //
  // The crate-private compression fault seam (the compression analogue of
  // `MockBackend::fail_on_call`) fails ONLY the first compression on this thread
  // -- attempt 0's finalize ratio -- so attempt 0's `+inf` ratio forces the
  // fallback and the higher-temperature attempt 1 is accepted; a second, clean
  // run accepts attempt 0. Runtime confirmation needs this seam: no ordinary
  // token input makes Foundation's zlib API error deterministically.
  //
  // Mutation: drop the `|| take_compression_error_swallowed()` at the fact merge
  // and run 1 reads `had_swallowed_error == Some(false)` and reproducible,
  // failing both assertions.
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];

  // One clean window (prompt [SOT, en, transcribe, <|notimestamps|>] forced over
  // the first 4 steps): a one-hot `hello` as the first free prediction -- a
  // genuine top-k draw at temperature > 0, but the peak dominates so the STEP is
  // deterministic and its compressed ratio stays well under threshold -- then
  // EOT. Two attempts' worth of steps, since a fallback resets the window decode.
  let build = || {
    let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
    for _ in 0..2 {
      mock.push_token_steps(&[2425, 2425, 2425, hello, s.end_token()]);
    }
    mock
  };
  // Base temperature 0.3 so even attempt 0 draws (threads the seed); the compression
  // ratio is the ONLY fallback trigger left, so attempt 0's swallowed `+inf`
  // forces exactly one fallback and the finite attempt 1 is accepted.
  let options = DecodingOptions::new()
    .with_temperature(0.3)
    .with_without_timestamps()
    .maybe_first_token_logprob_threshold(None)
    .maybe_logprob_threshold(None)
    .with_temperature_fallback_count(1) // attempts 0 and 1
    .with_seed(7);
  let compute = crate::audio::whisper::options::ComputeOptions::new();

  // Run 1: fail attempt 0's finalize compression (the thread's first).
  crate::audio::whisper::text::fault::reset_compression_faults();
  crate::audio::whisper::text::fault::fail_compression_on_call(1);
  let mock1 = build();
  let result1 = TranscribeTask::new(&mock1, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  crate::audio::whisper::text::fault::reset_compression_faults();

  assert_eq!(
    result1.task_facts().had_swallowed_error(),
    Some(true),
    "attempt 0's swallowed compression error -- its +inf ratio drove the fallback -- must be recorded"
  );
  assert!(
    (result1.segments_slice()[0].temperature() - 0.5).abs() < 1e-3,
    "the swallowed +inf rejected attempt 0 (0.3); attempt 1 (0.5) was accepted"
  );
  assert!(
    !crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &result1)
      .is_reproducible(),
    "a transcript that hinged on a swallowed OS error is not byte-reproducible"
  );

  // Run 2: no fault. Attempt 0's real (finite, low) ratio is accepted -- nothing
  // was swallowed, and the same seeded run now reproduces.
  let mock2 = build();
  let result2 = TranscribeTask::new(&mock2, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_ne!(
    result2.task_facts().had_swallowed_error(),
    Some(true),
    "a clean run swallowed nothing"
  );
  assert!(
    (result2.segments_slice()[0].temperature() - 0.3).abs() < 1e-3,
    "with no swallowed error attempt 0 (0.3) is accepted directly -- no fallback"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn segment_discovery_callback_fires_per_window() {
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let discovered = std::sync::Mutex::new(Vec::<usize>::new());
  let callback: &(dyn Fn(&[crate::audio::whisper::result::TranscriptionSegment]) + Sync) =
    &|segments| discovered.lock().unwrap().push(segments.len());
  let task = TranscribeTask::new(&mock, &t).with_segment_callback(callback);
  task
    .run(&vec![0.1; 32_000], &DecodingOptions::new())
    .unwrap();
  assert_eq!(discovered.lock().unwrap().as_slice(), &[1]);
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn failed_probe_rederives_language_from_that_attempts_decode() {
  // Regression (task-11 review, Important): TranscribeTask.swift:351-352
  // assigns the probe's outcome unconditionally (`try?` yields nil on
  // failure), so a later attempt's FAILED probe must clear the earlier
  // value and re-derive from that attempt's own decode result — never
  // stay sticky at the stale probe language.
  let t = tiny_tokenizer();
  let es = t.token_to_id("<|es|>").unwrap();
  let hello = t.encode(" Hello").unwrap()[0];
  let s = special();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  // Replayed from position 0 after every reset: serves attempt 0's probe
  // (one step) AND, after the probe's internal rewind, the decode itself.
  mock.push_token_steps(&[
    es,
    s.transcribe_token(),
    ts(0),
    hello,
    ts(100),
    ts(100),
    s.end_token(),
  ]);
  // Call ordinals (measured): probe0 = call 1 (succeeds, "es");
  // attempt-0 decode = call 2 only — decode_text's own first-token early
  // stop fires (forced "es" logprob ~-1.21 < -0.5 at t = 0) -> fallback;
  // probe1 = call 3 -> scripted to fail. Attempt 1's decode then rebuilds
  // the prompt with the default language and early-stops the same way,
  // so the ladder exhausts with attempt 1's result.
  mock.fail_on_call(3);

  let options = DecodingOptions::new()
    .with_detect_language()
    .with_temperature_fallback_count(1)
    .maybe_first_token_logprob_threshold(Some(-0.5))
    .maybe_logprob_threshold(None);
  let task = TranscribeTask::new(&mock, &t);
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  assert_eq!(
    result.language(),
    "en",
    "stale probe language must not survive a failed re-probe"
  );
  // The only enabled fallback trigger is the first-token comparison; it
  // fires on attempt 0 (stored counter = that fallback's 0-based attempt
  // index, TranscribeTask.swift:397) and attempt 1 accepts. The reset
  // count pins the full structure — probe0 + fallback + probe1 + window
  // — so a broken first-token comparison (no fallback, no re-probe)
  // fails here even though 0.0 is also the counter's default.
  assert_eq!(result.timings().total_decoding_fallbacks(), 0.0);
  assert_eq!(mock.counters().resets(), 4);
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn detect_language_pinned_deviation_actually_runs_the_probe() {
  // Closes the loop on `DecodingOptions::detect_language`'s pinned
  // deviation (also pinned at the options-getter level by
  // `options::tests::detect_language_pinned_construction_vs_mutation_histories`):
  // an unset `detect_language` with `use_prefill_prompt` mutated to
  // `false` in place resolves `true` on this port (Swift's equivalent
  // history stays `false`). This test proves that resolution is not
  // just a getter-level curiosity — it actually gates whether
  // `TranscribeTask::run` invokes the language-detection probe against
  // the backend, observed via `MockCounters` deltas between two
  // otherwise-identical runs.
  let t = tiny_tokenizer();
  let hello = t.encode(" Hello").unwrap()[0];

  // Shared recipe: prefill OFF (so `initial_prompt == [SOT]` on both
  // sides — one token, no task token anywhere in `current_tokens`,
  // which keeps `TimestampRulesFilter` a no-op for a multilingual model
  // per its own `effective_sample_begin` doc, so the scripted logits
  // reach the sampler unmodified), one fallback attempt
  // (`temperature_fallback_count(0)`), and the same first-token-logprob
  // trick `failed_probe_rederives_language_from_that_attempts_decode`
  // above uses: an unmasked one-hot step samples with logprob ~-1.21
  // against this tiny vocab's softmax denominator, comfortably below
  // -0.5, so `decode_text` breaks after exactly one `decode_step` call.
  // One scripted step serves either run: the probe (if it runs) and the
  // main decode both read script index 0 — the probe's own
  // unconditional reset rewinds the mock's script cursor before the
  // main decode starts (`decode::detect_language`'s own doc).
  let base_options = || {
    DecodingOptions::new()
      .maybe_use_prefill_prompt(false)
      .with_temperature_fallback_count(0)
      .maybe_first_token_logprob_threshold(Some(-0.5))
      .maybe_logprob_threshold(None)
  };

  // Probe disabled: explicit `false` beats the coupling even with
  // prefill off.
  let mut no_probe = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  no_probe.push_token_step(hello);
  let options_no_probe = base_options().maybe_detect_language(false);
  assert!(!options_no_probe.detect_language());
  TranscribeTask::new(&no_probe, &t)
    .run(&vec![0.1; 32_000], &options_no_probe)
    .unwrap();

  // Probe enabled: `detect_language` left unset, resolving `true` via
  // the pinned deviation — Swift's equivalent history
  // (`DecodingOptions()` then `usePrefillPrompt = false`) would stay
  // `false` and never run this probe at all.
  let mut with_probe = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  with_probe.push_token_step(hello);
  let options_with_probe = base_options();
  assert!(options_with_probe.detect_language());
  TranscribeTask::new(&with_probe, &t)
    .run(&vec![0.1; 32_000], &options_with_probe)
    .unwrap();

  // The delta IS the probe: one extra `decode_step` (the probe's own
  // one-shot draw) and one extra `reset_decoder_state`
  // (`decode::detect_language`'s own unconditional reset).
  let base = no_probe.counters();
  let probed = with_probe.counters();
  assert_eq!(
    probed.decode_steps(),
    base.decode_steps() + 1,
    "probe adds exactly one decode_step call"
  );
  assert_eq!(
    probed.resets(),
    base.resets() + 1,
    "probe adds exactly one reset_decoder_state call"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn all_masked_probe_does_not_fabricate_language() {
  // F3 (codex round 14). A valid tokenizer can resolve NO `<|lang|>` tokens
  // (an English-only vocab paired with a multilingual model, which the loader
  // never validates), so `LanguageLogitsFilter` masks EVERY entry and the
  // sampler returns the degenerate token 0 at `-inf`: the probe's `language_probs`
  // stays EMPTY, proving nothing was sampled. Yet the probe's `"en"` DISPLAY
  // default was UNCONDITIONALLY promoted to `observed_language`, fabricating a
  // detection the model never made -- and because language merging is first-wins,
  // that fabricated `"en"` then SUPPRESSED a genuine later `"es"`. Gate the
  // promotion on the probe actually having a predicted-language entry; the DISPLAY
  // language stays the Swift-faithful `"en"`.
  //
  // The all-masked probe is forced with an all-`-inf` first scripted step (the
  // probe's own logits), which after `LanguageLogitsFilter` leaves nothing to
  // sample regardless of the real tokenizer's language set. The main decode
  // re-reads that step as its SOT prefill (the sample is discarded), and
  // `first_token_logprob_threshold` is disabled so the degenerate `-inf` first
  // token does not early-complete the decode.
  //
  // Mutation: drop the `&& !probe.language_probs_slice().is_empty()` gate and the
  // empty-probs probe promotes `"en"` -- part 1 reads `Some("en")` and part 2's
  // fabricated `"en"` suppresses the predicted `"es"`, failing both `observed`
  // assertions.
  use crate::audio::whisper::backend::InferenceBackend;
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let hello = t.encode(" Hello").unwrap()[0];
  let all_masked = |vocab: usize| vec![f32::NEG_INFINITY; vocab];

  // Direct probe check: the all-masked probe samples no language token, so its
  // `language_probs` is empty and it falls back to the `"en"` DISPLAY default.
  let mut probe_mock = MockBackend::new();
  let vocab = probe_mock.dims().vocab();
  probe_mock.push_step(all_masked(vocab));
  let features = probe_mock.extract_features(&[0.0f32; 16]).unwrap();
  let encoded = probe_mock.encode(&features).unwrap();
  let mut state = probe_mock.new_decoder_state().unwrap();
  let mut sampler = GreedyTokenSampler::new(0.0, s.end_token(), &DecodingOptions::new());
  let mut timings = TranscriptionTimings::new();
  let probe = decode::detect_language(
    &probe_mock,
    &encoded,
    &mut state,
    &t,
    &mut sampler,
    &mut timings,
  )
  .unwrap();
  assert!(
    probe.language_probs_slice().is_empty(),
    "an all-masked probe sampled no language token, so it recorded no probability"
  );
  assert_eq!(
    probe.language(),
    crate::audio::whisper::constants::DEFAULT_LANGUAGE_CODE,
    "with nothing sampled the probe reports the Swift-faithful \"en\" DISPLAY default"
  );

  let options = DecodingOptions::new()
    .with_detect_language()
    .with_without_timestamps()
    .maybe_first_token_logprob_threshold(None);

  // Part 1 -- an all-masked probe, then a plain text decode: the display language
  // is the `"en"` default, but nothing was OBSERVED.
  let mut mock_a = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let vocab_a = mock_a.dims().vocab();
  mock_a.push_step(all_masked(vocab_a)); // probe step (re-read as the decode's SOT prefill)
  mock_a.push_token_steps(&[2425, 2425, hello, s.end_token()]);
  let result_a = TranscribeTask::new(&mock_a, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(
    result_a.language(),
    crate::audio::whisper::constants::DEFAULT_LANGUAGE_CODE,
    "the display language is the Swift-faithful \"en\" default"
  );
  assert_eq!(
    result_a.task_facts().observed_language(),
    None,
    "an all-masked probe observed nothing, so no language may be recorded"
  );

  // Part 2 -- the same all-masked probe, but the decode then PREDICTS `<|es|>`:
  // the observation must be the genuine `"es"`, no longer suppressed by a
  // fabricated `"en"`.
  let mut mock_b = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let vocab_b = mock_b.dims().vocab();
  mock_b.push_step(all_masked(vocab_b));
  mock_b.push_token_steps(&[2425, 2425, es, s.end_token()]);
  let result_b = TranscribeTask::new(&mock_b, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(
    result_b.language(),
    crate::audio::whisper::constants::DEFAULT_LANGUAGE_CODE,
    "the display language is still the forced-prefill \"en\""
  );
  assert_eq!(
    result_b.task_facts().observed_language(),
    Some("es"),
    "the genuinely predicted \"es\" is the observation, not a fabricated \"en\""
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn genuine_observation_survives_a_later_failed_probe() {
  // F2 (codex round 4), opposite direction of the zero-iteration bug. Window
  // 1's probe genuinely detects Spanish; window 2's probe FAILS. A failed
  // probe witnessed nothing, so it must NOT erase the earlier genuine
  // observation -- first-genuine-observation wins. Pre-fix the failed probe
  // cleared `observed_language` to `None`, and with the finalize fix in place
  // window 2's forced default `<|en|>` no longer re-observes either, so the
  // whole run reported NO detection even though window 1 plainly detected
  // "es".
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let hello = t.encode(" Hello").unwrap()[0];
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  // script[0] = <|es|>: the probe's language filter picks it as the detected
  // language. The main decode's prompt is then re-derived with a
  // `<|transcribe|>` task token, so `TimestampRulesFilter` masks language
  // tokens at the sampling position -- the decode itself predicts NO language
  // token, making the probe the sole observation. The ts(50) pair ends each
  // window and advances seek 1 s, giving two windows over 3 s of audio.
  mock.push_token_steps(&[
    es,
    s.transcribe_token(),
    ts(0),
    hello,
    ts(50),
    ts(50),
    s.end_token(),
  ]);
  // Window 1: probe = call 1 (succeeds, "es"), decode = calls 2..=8.
  // Window 2: probe = call 9 -> scripted to fail; its decode (calls 10..=16)
  // still runs. `fail_on_call` is reset-immune, so only window 2's probe fails.
  mock.fail_on_call(9);
  let options = DecodingOptions::new().with_detect_language();
  let task = TranscribeTask::new(&mock, &t);
  let result = task.run(&vec![0.1; 48_000], &options).unwrap();
  assert_eq!(mock.counters().encode_calls(), 2, "two windows decoded");
  assert_eq!(
    result.task_facts().observed_language(),
    Some("es"),
    "window 1's genuine detection must survive window 2's failed probe"
  );
}

/// The logprob `decode::detect_language` records for a one-hot `token` step,
/// measured through the probe itself rather than hand-derived from the
/// vocabulary size — the oracle the observation tests compare their carried
/// probabilities against (coremlit issue #107).
fn probe_logprob_for(t: &WhisperTokenizer, token: u32) -> f32 {
  use crate::audio::whisper::backend::InferenceBackend;
  let mut mock = MockBackend::new();
  mock.push_token_step(token);
  let features = mock.extract_features(&[0.0f32; 16]).unwrap();
  let encoded = mock.encode(&features).unwrap();
  let mut state = mock.new_decoder_state().unwrap();
  let mut sampler = GreedyTokenSampler::new(0.0, special().end_token(), &DecodingOptions::new());
  let mut timings = TranscriptionTimings::new();
  let probe =
    decode::detect_language(&mock, &encoded, &mut state, t, &mut sampler, &mut timings).unwrap();
  let probs = probe.language_probs_slice();
  assert_eq!(
    probs.len(),
    1,
    "a one-hot probe records exactly one language"
  );
  probs[0].1
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn every_kept_probe_reaches_the_result_as_a_spanned_observation() {
  // coremlit issue #107. Two windows, two DIFFERENT successful probes: the run
  // used to fold both into a last-write-wins display language and a first-wins
  // `observed_language` and DISCARD the windows, their spans and their
  // confidences. Both folds are unchanged -- the display is still window 2's
  // "ja", the observation still window 1's "es" -- and the probes themselves now
  // ride out as `language_observations`, in window order, spanned in the same
  // seconds base as the segments.
  //
  // Mutation proof: drop the `language_observations.push(..)` in `run` (or the
  // `.with_language_observations(..)` that carries it) and the list is empty
  // while BOTH scalars still read exactly as asserted below -- which is the
  // information loss this issue is about, invisible to every pre-existing
  // assertion.
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let ja = t.token_to_id("<|ja|>").unwrap();
  let hello = t.encode(" Hello").unwrap()[0];
  // `with_continuous_script`: each window (and its probe) consumes the NEXT
  // slice instead of replaying from 0, which is what lets window 2 probe a
  // different language than window 1. Per window: 1 probe step, then the 7
  // decode steps a `[SOT, <|lang|>, <|transcribe|>]` prefill takes to reach EOT.
  // The ts(50) pair ends each window and advances seek 1 s, giving two windows
  // over 3 s of audio.
  let mut mock = MockBackend::new()
    .with_dims(ModelDims::new().with_window_samples(16_000))
    .with_continuous_script();
  for language in [es, ja] {
    mock.push_token_steps(&[
      language, // the probe's own step
      language,
      s.transcribe_token(),
      ts(0),
      hello,
      ts(50),
      ts(50),
      s.end_token(),
    ]);
  }
  let options = DecodingOptions::new().with_detect_language();
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 48_000], &options)
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 2, "two windows decoded");

  // The folded scalars: UNCHANGED rules, now visible.
  assert_eq!(
    result.language(),
    "ja",
    "the DISPLAY language is still last-write-wins -- window 2's probe"
  );
  assert_eq!(
    result.task_facts().observed_language(),
    Some("es"),
    "the OBSERVATION is still first-genuine-wins -- window 1's probe"
  );

  // The evidence they were folded from.
  let observations = result.language_observations_slice();
  assert_eq!(
    observations.len(),
    2,
    "one entry per window that kept a probe"
  );
  let languages: Vec<&str> = observations
    .iter()
    .map(|observation| observation.detection().language())
    .collect();
  assert_eq!(languages, ["es", "ja"], "in window order, not fold order");
  let spans: Vec<(f32, f32)> = observations
    .iter()
    .map(|observation| (observation.start(), observation.end()))
    .collect();
  for (index, (expected, actual)) in [(0.0f32, 1.0f32), (1.0, 2.0)]
    .into_iter()
    .zip(spans.iter().copied())
    .enumerate()
  {
    assert!(
      (expected.0 - actual.0).abs() < 1e-3 && (expected.1 - actual.1).abs() < 1e-3,
      "window {index} spans the audio it decoded: expected {expected:?}, got {actual:?}"
    );
  }
  for (observation, token) in observations.iter().zip([es, ja]) {
    let probs = observation.detection().probs_slice();
    assert_eq!(
      probs.len(),
      1,
      "the probe records its single sampled language"
    );
    assert_eq!(probs[0].0, observation.detection().language());
    assert!(
      (probs[0].1 - probe_logprob_for(&t, token)).abs() < 1e-6,
      "the carried confidence is the probe's own, got {}",
      probs[0].1
    );
  }
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn an_observation_spans_exactly_what_its_own_window_segments_do() {
  // coremlit issue #107, the one-rounding-contract half: the observation and
  // the segments of the SAME window are both timed by
  // `segment::window_span`, so a short final window can never report one
  // extent to the observation list and a different one to the transcript.
  //
  // Two windows over 1.5 s with the end padding off: a full 1 s window, then
  // a 0.5 s tail. Each decodes a timestamp-less lump, whose single segment
  // therefore ends at the window's own end -- the exact quantity the
  // observation carries, so the two spans are comparable for equality.
  //
  // Mutation proof: span the observation with `window_samples` (the 30 s zero
  // pad's extent) instead of `segment_size` and window 2's observation ends
  // at 2.0 while its segment ends at 1.5; re-deriving either endpoint with
  // its own `as f32 / SAMPLE_RATE` division reds the helper tests in
  // `segment::tests` that this one shares its contract with.
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let hello = t.encode(" Hello").unwrap()[0];
  // Per window: 1 probe step, then the 4 decode steps a
  // `[SOT, <|lang|>, <|transcribe|>]` prefill takes to reach EOT with no
  // timestamp token anywhere -- which is what makes the segment a lump
  // spanning the whole window.
  let mut mock = MockBackend::new()
    .with_dims(ModelDims::new().with_window_samples(16_000))
    .with_continuous_script();
  for _ in 0..2 {
    mock.push_token_steps(&[es, es, s.transcribe_token(), hello, s.end_token()]);
  }
  // `window_clip_time` 0: the default 1 s of end padding would put
  // `clip_guard` at 8_000 and the tail window would never be entered at all.
  let options = DecodingOptions::new()
    .with_detect_language()
    .with_window_clip_time(0.0);
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 24_000], &options)
    .unwrap();
  assert_eq!(
    mock.counters().encode_calls(),
    2,
    "a full 1 s window and a 0.5 s tail"
  );

  let observations = result.language_observations_slice();
  assert_eq!(observations.len(), 2, "both windows kept a probe");
  let segments = result.segments_slice();
  for (index, (seek, samples)) in [(0usize, 16_000usize), (16_000, 8_000)]
    .into_iter()
    .enumerate()
  {
    let expected = segment::window_span(seek, samples);
    let observation = &observations[index];
    assert_eq!(
      (observation.start(), observation.end()),
      expected,
      "window {index} observation spans the audio it held, not the zero pad"
    );
    let window_segments: Vec<&TranscriptionSegment> = segments
      .iter()
      .filter(|segment| segment.seek() == seek)
      .collect();
    assert_eq!(
      window_segments.len(),
      1,
      "window {index} lumps into one segment"
    );
    assert_eq!(
      (window_segments[0].start(), window_segments[0].end()),
      expected,
      "window {index} segment carries the SAME span its observation does"
    );
  }
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn no_probe_records_no_observation() {
  // coremlit issue #107. The list is exactly "the probes that ran and were
  // kept": detection OFF runs none, so it stays EMPTY rather than gaining a
  // placeholder built from the display language -- which would be the same
  // fabrication the all-masked-probe gate (F3, codex round 14) refuses for
  // `observed_language`, one door further out.
  //
  // Mutation proof: push an observation unconditionally (from
  // `detected_language` rather than the kept probe) and this reads back one
  // entry carrying the Swift-faithful `"en"` display default no probe ever
  // produced.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let options = DecodingOptions::new();
  assert!(
    !options.detect_language(),
    "no probe: prefill is on by default"
  );
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 1, "one window decoded");
  assert_eq!(result.language(), "en", "the display fallback is kept");
  assert!(
    result.language_observations_slice().is_empty(),
    "no probe ran, so no observation may be recorded"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_retried_window_records_only_the_kept_attempts_probe() {
  // coremlit issue #107. The probe runs once per ATTEMPT, so a window the
  // fallback ladder retries probes twice -- but only the attempt whose decode
  // was KEPT produced the transcript, and the list is per-WINDOW evidence, not
  // per-attempt. One window, two attempts, exactly one observation spanning the
  // whole window.
  //
  // Mutation proof: push the observation inside `decode_with_fallback`'s attempt
  // loop instead of once per window in `run`, and this reads back 2 entries with
  // identical spans -- a code-switch geography that invents a switch out of a
  // temperature retry.
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  // `with_continuous_script` so the probe step and the decode steps are laid out
  // explicitly per attempt rather than replayed from 0. Per attempt: the probe's
  // `<|es|>` step, then the PROVEN catastrophic-avg-logprob decode (4 flat steps
  // + EOT) that `fallback_ladder_retries_with_rising_temperature_then_accepts`
  // derives -- it falls back on EVERY attempt, so the ladder exhausts and the
  // final attempt's result stands.
  let mut mock = MockBackend::new()
    .with_dims(ModelDims::new().with_window_samples(16_000))
    .with_continuous_script();
  for _ in 0..2 {
    mock.push_token_step(es);
    for _ in 0..4 {
      let mut flat = vec![0.0f32; 51865];
      flat[s.end_token() as usize] = -20.0;
      mock.push_step(flat);
    }
    mock.push_token_step(s.end_token());
  }
  let options = DecodingOptions::new()
    .with_detect_language()
    .with_without_timestamps()
    .maybe_first_token_logprob_threshold(None)
    .maybe_compression_ratio_threshold(None)
    .with_temperature_fallback_count(1); // attempts 0 and 1
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 1, "one window, retried");
  assert_eq!(
    mock.counters().decode_steps(),
    12,
    "two attempts, each a probe step plus five decode steps"
  );
  let observations = result.language_observations_slice();
  assert_eq!(observations.len(), 1, "one window, one kept probe");
  assert_eq!(observations[0].detection().language(), "es");
  assert!(
    (observations[0].start() - 0.0).abs() < 1e-3 && (observations[0].end() - 1.0).abs() < 1e-3,
    "the observation spans the window, not an attempt: got {:?}",
    (observations[0].start(), observations[0].end())
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn vad_chunked_observations_reanchor_and_concatenate() {
  // coremlit issue #107, at the VAD door -- the one the issue's own bilingual
  // long-track use case goes through. The same three-chunk audio as
  // `vad_chunked_transcribe_reanchors_and_merges`, with the probe on: each
  // chunk's `run` spans its observation CHUNK-relative, so the merged result is
  // only honest if `apply_result_seek_offset` shifts those spans with the
  // segments and the merge concatenates them.
  //
  // Mutation proof: drop the observation loop in `apply_result_seek_offset` and
  // all three starts read 0.0 against absolute segment times; drop the
  // concatenation in `merge_results` and the merged list is empty while each
  // chunk still probed.
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let hello = t.encode(" Hello").unwrap()[0];
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  // `script_clean_window` with the leading `<|en|>` replaced by `<|es|>`: the
  // probe reads step 0 and the reset rewinds the cursor, so the decode replays
  // the same slice and each chunk decodes one "Hello" window as before.
  mock.push_token_steps(&[
    es,
    s.transcribe_token(),
    ts(0),
    hello,
    ts(100),
    ts(100),
    s.end_token(),
  ]);
  let kit = WhisperKit::with_backend(mock, t);
  let mut audio = vec![0.1f32; 96_000];
  audio[32_000..35_200].fill(0.0);
  audio[64_000..67_200].fill(0.0);
  let options = DecodingOptions::new()
    .with_chunking_strategy(ChunkingStrategy::Vad)
    .with_detect_language();
  let result = kit.transcribe(&audio, &options).unwrap();
  assert_eq!(result.text(), "Hello Hello Hello", "per-chunk texts joined");
  let observations = result.language_observations_slice();
  assert_eq!(observations.len(), 3, "every chunk's kept probe is carried");
  for observation in observations {
    assert_eq!(observation.detection().language(), "es");
  }
  // Chunk offsets 0 / 33_600 / 65_600 -> 0.0 / 2.1 / 4.1 s. The .1 offsets are
  // the chunk boundaries and CANNOT come from an un-re-anchored chunk-relative
  // span (which would start every observation at 0.0).
  let starts: Vec<f32> = observations
    .iter()
    .map(crate::audio::whisper::transcribe::LanguageObservation::start)
    .collect();
  for (index, expected) in [0.0f32, 2.1, 4.1].into_iter().enumerate() {
    assert!(
      (starts[index] - expected).abs() < 1e-3,
      "chunk {index} observation re-anchored to {expected}, got {}",
      starts[index]
    );
  }
  // Each chunk spans its own content (33_600 / 32_000 / 30_400 samples), shifted
  // onto the absolute timeline: the spans tile the audio with no gap.
  let ends: Vec<f32> = observations
    .iter()
    .map(crate::audio::whisper::transcribe::LanguageObservation::end)
    .collect();
  for (index, expected) in [2.1f32, 4.1, 6.0].into_iter().enumerate() {
    assert!(
      (ends[index] - expected).abs() < 1e-3,
      "chunk {index} observation ends at {expected}, got {}",
      ends[index]
    );
  }
  assert_eq!(
    result.task_facts().observed_language(),
    Some("es"),
    "the folded observation is unchanged by the list beside it"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_predicted_language_is_recorded_over_the_forced_display_language() {
  // F1 (codex round 5). The default multilingual prefill FORCES `<|en|>` into
  // the prompt, and `without_timestamps` (a public config) drops the
  // `TimestampRulesFilter`, so the model can freely PREDICT `<|es|>` at the
  // first free position after it. The Swift-faithful DISPLAY language is the
  // FIRST language token in the whole slice -- the forced `<|en|>` -- while the
  // OBSERVATION is the PREDICTED `<|es|>`.
  //
  // Pre-fix, `decode_with_fallback` reconstructed the observation from the
  // display `result.language()` (the forced `<|en|>`), recording `"en"` for a
  // run that plainly detected `"es"`; the observation now flows from the
  // decode's own `observed_language`, so the display stays `"en"` and the
  // detection is `"es"`.
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  // Prefill [SOT, <|en|>, <|transcribe|>, <|notimestamps|>] forces positions
  // 0..=3; the first FREE prediction is `<|es|>`, then a text token, then EOT.
  mock.push_token_steps(&[
    s.english_token(),
    s.transcribe_token(),
    s.no_timestamps_token(),
    es,
    2425,
    s.end_token(),
  ]);
  // Default `detect_language()` is false (use_prefill_prompt is set), so NO
  // probe runs: the observation can only come from the decode's predicted token.
  let options = DecodingOptions::new().with_without_timestamps();
  assert!(
    !options.detect_language(),
    "no probe: prefill is on by default"
  );
  let task = TranscribeTask::new(&mock, &t);
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();

  assert_eq!(
    result.language(),
    "en",
    "the DISPLAY language is the forced-prefill <|en|>, kept Swift-faithful"
  );
  assert_eq!(
    result.task_facts().observed_language(),
    Some("es"),
    "the DETECTION is the PREDICTED <|es|>, not the forced display <|en|>"
  );
  assert_eq!(
    crate::audio::whisper::provenance::Provenance::for_result(
      &options,
      &crate::audio::whisper::options::ComputeOptions::new(),
      &result,
    )
    .task_facts()
    .observed_language(),
    Some("es"),
    "provenance records the predicted detection, never the forced display"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn transcribe_all_preserves_order_across_scoped_threads() {
  let t = tiny_tokenizer();
  // The mock's script cursor lives in each worker's OWN MockDecoderState
  // (Task 2), so concurrent workers replay the same script independently;
  // only the counters are shared. One scripted window serves both audios.
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let kit = WhisperKit::with_backend(mock, t);
  let a = vec![0.1f32; 32_000];
  let b = vec![0.1f32; 32_000];
  let results = kit.transcribe_all(&[&a, &b], &DecodingOptions::new());
  assert_eq!(results.len(), 2);
  for result in results {
    assert_eq!(result.unwrap().text(), "Hello");
  }
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn vad_chunked_transcribe_reanchors_and_merges() {
  // Regression (task-12 review, Important): the VAD branch itself —
  // chunk_all splitting, per-chunk clip clearing, apply_seek_offsets
  // re-anchoring, and merge_transcription_results — had no direct test.
  // Silence frames at 32_000..35_200 and 64_000..67_200 make
  // split_on_middle_of_longest_silence cut at 33_600 and 65_600, giving
  // three chunks (offsets 0 / 33_600 / 65_600), each decoding one
  // scripted "Hello" window.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let kit = WhisperKit::with_backend(mock, t);
  let mut audio = vec![0.1f32; 96_000];
  audio[32_000..35_200].fill(0.0);
  audio[64_000..67_200].fill(0.0);
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);
  let result = kit.transcribe(&audio, &options).unwrap();
  assert_eq!(result.text(), "Hello Hello Hello", "per-chunk texts joined");
  let segments = result.segments_slice();
  assert_eq!(segments.len(), 3);
  let ids: Vec<usize> = segments.iter().map(|s| s.id()).collect();
  assert_eq!(
    ids,
    vec![0, 1, 2],
    "merge re-ids result_index + segment_index"
  );
  let starts: Vec<f32> = segments.iter().map(|s| s.start()).collect();
  assert!((starts[0] - 0.0).abs() < 1e-3);
  // 33_600 / 16_000 = 2.1 s and 65_600 / 16_000 = 4.1 s: the .1 offsets
  // are the chunk boundaries and CANNOT come from the un-chunked path
  // (whose window seeks land on whole timestamps, 2.0 / 4.0).
  assert!(
    (starts[1] - 2.1).abs() < 1e-3,
    "chunk 2 re-anchored, got {}",
    starts[1]
  );
  assert!(
    (starts[2] - 4.1).abs() < 1e-3,
    "chunk 3 re-anchored, got {}",
    starts[2]
  );
  // All three chunks survived, so their ordered coordinates concatenate through
  // the fixed schedule merge (round 10, F2) -- a fully-known ordered attribution,
  // NOT the pre-fix first-child-only [0].
  assert_eq!(
    result.task_facts().worker_schedule(),
    Some([0, 1, 2].as_slice()),
    "every chunk survived -- the ordered coordinates concatenate to [0, 1, 2]",
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn worker_schedule_is_unknown_when_a_vad_chunk_errors() {
  // ADJUDICATED (round 10, F2): a VAD chunk that ERRORS and is dropped contributes
  // an UNKNOWN (`None`) schedule, not a missing coordinate -- and under the
  // absorbing-`None` schedule law that taints the whole run's schedule to `None`,
  // distinct from the surviving chunks' hand-selected `[1, 2]`. A run that lost a
  // chunk cannot report a fully-known ordered worker attribution.
  //
  // Same 3-chunk audio as `vad_chunked_transcribe_reanchors_and_merges`, but
  // chunk 0's first decode_step fails (`fail_on_call(1)`), so its whole run errors
  // and the VAD branch drops it; chunks 1 and 2 replay the script from their own
  // resets and survive with known coordinates [1] and [2].
  //
  // Mutation proof: seed the schedule fold from the merged survivors (hand-select
  // the successes) instead of folding the errored chunk's `None`, and this reads
  // back `Some([1, 2])` instead of the adjudicated `None`.
  //
  // Round 11 (M2) extends this history to the SWALLOWED-ERROR facts. The drop is a
  // hidden, transcript-controlling error, so the run must not claim byte
  // reproducibility: `had_swallowed_error` reads `Some(true)`, the decoded span's
  // exact total is unknown (the dropped chunk may have allocated ordinals) yet the
  // survivors' ordinals lower-bound it to `AtLeast(2)` (round 12), and
  // `Provenance::is_reproducible` is false. The mock's `fail_on_call` is a
  // reset-immune ORDINAL, so a SECOND identical `kit.transcribe` -- same object,
  // audio, and options -- does not fail call 1 again, all three chunks survive, and
  // the transcript is DIFFERENT ("Hello Hello Hello"): concrete proof the first
  // result's reproducibility claim would have been false.
  //
  // Mutation proof (round 11): drop the `.with_had_swallowed_error(true)` at the
  // VAD chunk-drop site (transcribe/mod.rs) and the first result reads back
  // reproducible, failing the `!is_reproducible()` assertion below.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  mock.fail_on_call(1); // chunk 0's first decode_step errors -> its run is dropped
  let kit = WhisperKit::with_backend(mock, t);
  let mut audio = vec![0.1f32; 96_000];
  audio[32_000..35_200].fill(0.0);
  audio[64_000..67_200].fill(0.0);
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);
  let result = kit.transcribe(&audio, &options).unwrap();
  assert_eq!(
    result.text(),
    "Hello Hello",
    "chunk 0 errored and was dropped; only chunks 1 and 2 survive",
  );
  assert_eq!(
    result.task_facts().worker_schedule(),
    None,
    "an errored chunk taints the ordered schedule to unknown -- NOT the survivors' [1, 2]",
  );
  assert_eq!(
    result.task_facts().had_swallowed_error(),
    Some(true),
    "the dropped chunk's swallowed error is recorded as an outcome fact",
  );
  assert_eq!(
    result.task_facts().decoded_span(),
    SpanKnowledge::AtLeast(2),
    "an errored chunk leaves the exact total unknown, but the two surviving chunks' \
     ordinals still lower-bound the run's span (round 12; was the bound-less None)",
  );
  let compute = crate::audio::whisper::options::ComputeOptions::new();
  assert!(
    !crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &result)
      .is_reproducible(),
    "a run that silently dropped a chunk cannot promise byte reproducibility",
  );

  // The reset-immune ordinal makes the falseness of that claim concrete: a second
  // identical call does NOT re-fail call 1, so all three chunks survive.
  let second = kit.transcribe(&audio, &options).unwrap();
  assert_eq!(
    second.text(),
    "Hello Hello Hello",
    "the second same-input call keeps chunk 0 -- a different transcript",
  );
  assert_ne!(
    result.text(),
    second.text(),
    "same object, audio, and options -> different output: not reproducible",
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn vad_detector_swap_changes_chunk_boundaries() {
  // coremlit issue #9 ("Make VAD strategy pluggable or configurable
  // rather than locking product behavior to the default energy VAD"):
  // reuses `vad_chunked_transcribe_reanchors_and_merges`'s exact audio
  // (two silent stretches inside 96_000 samples, 48_000-sample windows)
  // but swaps in a detector that never reports silence. With no silence
  // to split on, `split_on_middle_of_longest_silence` falls through to
  // its `None => end` arm every time instead of cutting at a silence
  // midpoint, so chunking lands on whole-window boundaries (2 chunks of
  // 48_000 samples each, second chunk starting at exactly 3.0 s) instead
  // of the default `EnergyVad`'s silence-cut boundaries (3 chunks,
  // starting at 0 / 2.1 / 4.1 s, pinned above) -- an observable chunking
  // difference driven purely by which detector is plugged in.
  //
  // Unit struct: no fields, so it is trivially `Send + Sync + 'static`
  // (auto traits with nothing in the type to violate them) -- it
  // satisfies `set_vad_detector`'s actual bounds, and compiling below is
  // the positive-case proof of that, complementing that method's
  // `compile_fail` doctest, which rejects a detector holding non-`Send`
  // state.
  struct AlwaysActiveVad;
  impl VoiceActivityDetector for AlwaysActiveVad {
    fn voice_activity(&self, samples: &[f32]) -> Vec<bool> {
      vec![true; samples.len().div_ceil(self.frame_length_samples())]
    }
    fn frame_length_samples(&self) -> usize {
      crate::audio::whisper::audio::vad::DEFAULT_FRAME_LENGTH_SAMPLES
    }
  }

  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let kit = WhisperKit::with_backend(mock, t).with_vad_detector(Box::new(AlwaysActiveVad));
  let mut audio = vec![0.1f32; 96_000];
  audio[32_000..35_200].fill(0.0);
  audio[64_000..67_200].fill(0.0);
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);
  let result = kit.transcribe(&audio, &options).unwrap();
  assert_eq!(result.text(), "Hello Hello", "2 whole-window chunks, not 3");
  let segments = result.segments_slice();
  assert_eq!(segments.len(), 2);
  assert!((segments[0].start() - 0.0).abs() < 1e-3);
  assert!(
    (segments[1].start() - 3.0).abs() < 1e-3,
    "chunk 2 starts at the whole-window boundary (48_000 / 16_000), got {}",
    segments[1].start()
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn transcribe_surfaces_a_latched_vad_failure_instead_of_ok() {
  // Regression (vadkit-fence Medium): a hard VAD *model* failure during
  // chunking must be observable from the same `transcribe` call, not
  // swallowed into false silence. A detector that latches an inference
  // failure — the mock-backend fail pattern, standing in for the Silero
  // CoreML model failing mid-stream — reports all-inactive frames, which on
  // their own would let `chunk_all` split the window and `transcribe` return
  // an `Ok` transcript off silently-degraded boundaries. Whisperkit's
  // transcribe instead snapshots the detector's failure generation across
  // chunking (via `VoiceActivityDetector::detection_generation`) and, seeing
  // it advance, surfaces `TranscribeError::Vad`.
  //
  // Mutation: drop the `detection_generation` check in `WhisperKit::transcribe`
  // → the latched failure is ignored, the unscripted chunks decode/drop to an
  // empty `Ok`, and this `expect_err` goes red.
  #[derive(Default)]
  struct FailingVad {
    fired: std::sync::Mutex<bool>,
  }
  impl VoiceActivityDetector for FailingVad {
    fn voice_activity(&self, samples: &[f32]) -> Vec<bool> {
      *self.fired.lock().unwrap() = true;
      // A hard failure is indistinguishable from silence at the trait
      // boundary — exactly the degradation the latch exists to catch.
      vec![false; samples.len().div_ceil(self.frame_length_samples())]
    }
    fn frame_length_samples(&self) -> usize {
      crate::audio::whisper::audio::vad::DEFAULT_FRAME_LENGTH_SAMPLES
    }
    fn detection_generation(&self) -> u64 {
      // One latched failure once `voice_activity` has run; monotonic, so the
      // generation transcribe snapshots before chunking (0) differs from the
      // one it reads after (1).
      u64::from(*self.fired.lock().unwrap())
    }
    fn last_detection_error(&self) -> Option<Box<dyn std::error::Error + Send + Sync + 'static>> {
      self
        .fired
        .lock()
        .unwrap()
        .then(|| "scripted VAD inference failure".into())
    }
  }

  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let kit = WhisperKit::with_backend(mock, t).with_vad_detector(Box::new(FailingVad::default()));
  // Longer than one window, so the VAD chunking branch runs the detector.
  let audio = vec![0.1f32; 96_000];
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);

  let error = kit
    .transcribe(&audio, &options)
    .expect_err("a latched hard VAD failure must fail transcription, not return Ok");
  assert!(
    matches!(error, TranscribeError::Vad(VadError::Detection(_))),
    "expected TranscribeError::Vad, got {error:?}"
  );
  assert!(
    error
      .to_string()
      .contains("voice-activity detection failed"),
    "the error should render the VAD stage, got: {error}"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn concurrent_transcribe_cannot_steal_a_latched_vad_failure() {
  // Regression (vadkit-fence Medium): `SileroVad` is `Send + Sync` and
  // documented as shareable, so two `transcribe` calls can drive one detector
  // at once. The failure latch must not be a slot one caller can drain out from
  // under another: with the old destructive `take`, caller B's pre-clear —
  // landing between A's latch and A's post-chunk check — discarded A's error
  // and A returned `Ok` off silently-degraded boundaries. The fix makes each
  // run's source of truth a monotonic `detection_generation` it snapshots and
  // re-reads, which no other run can clear, so A still fails closed even though
  // B destructively drains the recorded error detail mid-race.
  //
  // Determinism: two barriers (no sleeps) pin the exact interleaving — A
  // latches, THEN B drains, THEN A reaches its post-chunk generation check.
  //
  // Mutation: revert `transcribe` to decide via the drainable error slot
  // (`last_detection_error().is_some()`, the old `take`-shaped check) instead
  // of the generation delta → B's mid-race drain empties the slot, A reads
  // `None`, returns `Ok`, and this assertion goes red.
  use std::sync::{
    Arc, Barrier, Mutex,
    atomic::{AtomicBool, Ordering},
  };

  // Shared latch state, faithful to `SileroVad`'s: a monotonic generation and a
  // most-recent-error slot, plus the two rendezvous the stealer thread uses. A
  // plain `String` stands in for the model's `InferError` (which the whisperkit
  // test crate cannot construct — it is `#[non_exhaustive]`).
  struct Shared {
    generation: Mutex<u64>,
    last_error: Mutex<Option<String>>,
    coordinated: AtomicBool,
    after_latch: Barrier,
    after_steal: Barrier,
  }
  impl Shared {
    // The stealer's destructive drain — exactly what the old pre-clear `take`
    // did to a concurrent run's recorded error.
    fn steal(&self) {
      self.last_error.lock().unwrap().take();
    }
  }

  struct RacingVad(Arc<Shared>);
  impl VoiceActivityDetector for RacingVad {
    fn voice_activity(&self, samples: &[f32]) -> Vec<bool> {
      let s = &self.0;
      // Latch a hard failure exactly ONCE — on the first call — and hand off to
      // the stealer while latched. `chunk_all` drives the detector once per
      // window, so a later call must NOT re-record the error: that would paper
      // over B's mid-race steal and mask the very bug under test.
      if !s.coordinated.swap(true, Ordering::SeqCst) {
        *s.generation.lock().unwrap() += 1;
        *s.last_error.lock().unwrap() = Some("scripted concurrent VAD failure".to_owned());
        s.after_latch.wait(); // release B to steal the recorded detail
        s.after_steal.wait(); // B has stolen; let A proceed to its check
      }
      // A hard failure is indistinguishable from silence at the trait boundary.
      vec![false; samples.len().div_ceil(self.frame_length_samples())]
    }
    fn frame_length_samples(&self) -> usize {
      crate::audio::whisper::audio::vad::DEFAULT_FRAME_LENGTH_SAMPLES
    }
    fn detection_generation(&self) -> u64 {
      *self.0.generation.lock().unwrap()
    }
    fn last_detection_error(&self) -> Option<Box<dyn std::error::Error + Send + Sync + 'static>> {
      self.0.last_error.lock().unwrap().clone().map(Into::into)
    }
  }

  let shared = Arc::new(Shared {
    generation: Mutex::new(0),
    last_error: Mutex::new(None),
    coordinated: AtomicBool::new(false),
    after_latch: Barrier::new(2),
    after_steal: Barrier::new(2),
  });

  let t = tiny_tokenizer();
  let mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  let kit =
    WhisperKit::with_backend(mock, t).with_vad_detector(Box::new(RacingVad(shared.clone())));
  // Longer than one window, so the VAD chunking branch runs the detector. A
  // fails closed at the post-chunk check, BEFORE any decode, so the backend is
  // never driven and needs no scripting.
  let audio = vec![0.1f32; 96_000];
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);

  let result = std::thread::scope(|scope| {
    // A: the real transcribe whose VAD run latches a hard failure.
    let a = scope.spawn(|| kit.transcribe(&audio, &options));
    // B: a concurrent run standing in for the old destructive pre-clear — it
    // drains A's recorded error the instant A has latched it.
    let b_shared = Arc::clone(&shared);
    let b = scope.spawn(move || {
      b_shared.after_latch.wait(); // A has latched
      b_shared.steal(); // discard A's recorded error mid-flight
      b_shared.after_steal.wait(); // let A reach its post-chunk check
    });
    b.join().unwrap();
    a.join().unwrap()
  });

  assert!(
    matches!(result, Err(TranscribeError::Vad(VadError::Detection(_)))),
    "A must fail closed on its own generation delta even though B drained the \
     recorded error mid-race, got {result:?}"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn zero_max_window_seek_terminates() {
  // Regression (phase-gate round 3): `Some(0)` reached the seek clamp as
  // `min(seek, previous_seek + 0)`, re-decoding the same window forever.
  // The cap now floors at one sample of progress: audio 3 samples past
  // the window guard yields exactly 3 one-sample windows, then stops.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let task = TranscribeTask::new(&mock, &t);
  let options = DecodingOptions::new().with_max_window_seek(0);
  let result = task.run(&vec![0.1; 16_003], &options).unwrap();
  assert_eq!(
    result.segments_slice().len(),
    3,
    "one window per floored sample"
  );
  // Saturation half: a cap near usize::MAX must not overflow the sum.
  let options = DecodingOptions::new().with_max_window_seek(usize::MAX);
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  assert_eq!(
    result.segments_slice().len(),
    1,
    "uncapped-in-practice advance"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn out_of_range_clip_end_terminates_at_physical_audio() {
  // Regression (phase-gate round 4, High): a clip end beyond the audio
  // keeps `clip_guard` unsatisfied after `seek` reaches the physical
  // end; `segment_size` hits zero and — `without_timestamps`, where the
  // seek advance IS `segment_size` — the loop re-decoded padded silence
  // forever. The zero-size guard now breaks to the next clip.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  let s = special();
  // without_timestamps prompt: [sot, en, transcribe, no_ts]; forced
  // predictions consume script[0..2], then sampled hello + EOT.
  mock.push_token_steps(&[
    s.english_token(),
    s.transcribe_token(),
    s.no_timestamps_token(),
    hello,
    s.end_token(),
  ]);
  let task = TranscribeTask::new(&mock, &t);
  let options = DecodingOptions::new()
    .with_without_timestamps()
    .with_clip_timestamps(vec![0.0, 4.0]); // 64_000 samples of clip over 32_000 of audio
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  // Two real 1-second windows fit the physical audio; the third
  // iteration's zero segment breaks instead of decoding padding forever.
  assert_eq!(result.segments_slice().len(), 2);
  assert_eq!(
    mock.counters().encode_calls(),
    2,
    "no empty-window inference"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn early_stop_does_not_leak_into_fallback_retries() {
  // Regression (phase-gate round 5): the early-stop latch was allocated
  // once per window, so a callback-stopped attempt whose partial result
  // triggered an ordinary fallback handed the still-true flag to the
  // retry, truncating it after one step — Swift initializes a fresh
  // latch per decodeText (TextDecoder.swift:570).
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let calls = std::sync::Mutex::new(0usize);
  let callback: &(
     dyn Fn(&crate::audio::whisper::result::TranscriptionProgress) -> Option<bool> + Sync
   ) = &|_progress| {
    let mut seen = calls.lock().unwrap();
    *seen += 1;
    // Call 6 = attempt 0's third sampled step (after hello + both
    // timestamps landed): request the stop. Every other call continues.
    Some(*seen != 6)
  };
  let task = TranscribeTask::new(&mock, &t).with_progress_callback(callback);
  // At t = 0 the window averages ~-0.19 (hello's one-hot logprob -1.21
  // diluted by prefill/EOT zeros and the mass-rule-boosted timestamp
  // logprobs of ~-0.07); at t = 0.2 every draw scores ~0. A -0.1
  // threshold therefore fails attempt 0's stopped partial and accepts
  // the full retry. A leaked stale flag instead breaks the retry after
  // one step. (The first-token threshold stays disabled: it would
  // complete attempt 0 at its very first iteration, before any callback
  // can fire.)
  let options = DecodingOptions::new()
    .with_temperature_fallback_count(1)
    .maybe_first_token_logprob_threshold(None)
    .maybe_logprob_threshold(Some(-0.1));
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  assert_eq!(result.text(), "Hello", "the retry ran to completion");
  assert_eq!(
    mock.counters().decode_steps(),
    13,
    "6 stopped steps + 7 full-retry steps"
  );
  assert_eq!(result.timings().total_decoding_fallbacks(), 0.0);
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_rejected_attempts_early_stop_survives_the_fallback_selection() {
  // R6-F1 (codex round 6). A callback truncates attempt 0, whose bad partial then
  // CROSSES the logprob threshold and falls back; attempt 1 runs to completion
  // and is accepted WITHOUT stopping. The accepted attempt was not truncated, so
  // the pre-fix accepted-only read (`decoding_result.early_stopped()`) recorded
  // early_stopped=false -- losing the history that a callback stop fired at all.
  // The unified sink OR-s the rejected attempt's stop before the fallback drops
  // it, so the fact survives to the accepted result, and the two runs -- one with
  // the callback, one without -- leave DISTINCT records even though their text is
  // identical: the truncated one is not reproducible from the options alone.
  //
  // Mutation proof: revert `decode_with_fallback` to merge `false` for the early
  // stop (or read only the accepted `DecodingResult::early_stopped`) and the
  // `early_stopped()` assertion below fails, reading back false.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let compute = crate::audio::whisper::options::ComputeOptions::new();
  // Same fallback-forcing configuration as the leak test above, but with a ZERO
  // fallback increment so the accepted retry stays greedy (temperature 0.0) and
  // never DRAWS -- isolating the early-stop fact as the only thing that can move
  // the reproducibility answer between the two runs below.
  let options = DecodingOptions::new()
    .with_temperature_fallback_count(1)
    .with_temperature_increment_on_fallback(0.0)
    .maybe_first_token_logprob_threshold(None)
    .maybe_logprob_threshold(Some(-0.1));

  // WITHOUT a callback: attempt 0 runs full, still fails the threshold, falls
  // back, and the greedy attempt 1 is accepted -- an un-truncated, non-sampling,
  // reproducible run.
  let uncut = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(uncut.text(), "Hello");
  assert_eq!(uncut.task_facts().early_stopped(), Some(false));
  assert_eq!(
    uncut.task_facts().drew_from_rng(),
    Some(false),
    "greedy retry never draws"
  );
  let uncut_prov =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &uncut);
  assert!(uncut_prov.is_reproducible());

  // WITH a callback that stops attempt 0's third sampled step (call 6, exactly as
  // the leak test): the rejected attempt is truncated, attempt 1 completes.
  let calls = std::sync::Mutex::new(0usize);
  let callback: &(
     dyn Fn(&crate::audio::whisper::result::TranscriptionProgress) -> Option<bool> + Sync
   ) = &|_progress| {
    let mut seen = calls.lock().unwrap();
    *seen += 1;
    Some(*seen != 6)
  };
  let truncated = TranscribeTask::new(&mock, &t)
    .with_progress_callback(callback)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(
    truncated.text(),
    "Hello",
    "the accepted retry still ran to completion"
  );
  assert_eq!(
    truncated.task_facts().early_stopped(),
    Some(true),
    "the REJECTED attempt's early stop must survive the fallback selection"
  );
  assert_eq!(
    truncated.task_facts().drew_from_rng(),
    Some(false),
    "the greedy retry never draws, so early_stopped is the ONLY differing fact"
  );
  let trunc_prov =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &truncated);
  assert_eq!(trunc_prov.task_facts().early_stopped(), Some(true));
  assert!(
    !trunc_prov.is_reproducible(),
    "a callback truncation -- even of a rejected attempt -- is not reproducible from options alone"
  );
  assert_ne!(
    uncut_prov, trunc_prov,
    "the surviving early-stop fact distinguishes two runs whose text is identical"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_callback_truncation_is_recorded_and_is_not_reproducible() {
  // F4a (codex round 5). A progress callback returning Some(false) TRUNCATES the
  // transcript -- a caller CONTROL action -- but the callback is a closure the
  // record cannot name. Two runs differing ONLY in that callback must NOT leave
  // byte-identical, both-reproducible provenance: the truncated one records the
  // early-stop OUTCOME (library-known) and is not reproducible from the recorded
  // options+seed alone, while the un-truncated one is (greedy). Pre-fix both
  // recorded nothing of the callback and both claimed `is_reproducible()`.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let options = DecodingOptions::new();
  let compute = crate::audio::whisper::options::ComputeOptions::new();

  // WITHOUT a callback: the full greedy transcript, reproducible from options.
  let full = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(
    full.task_facts().early_stopped(),
    Some(false),
    "no callback truncated the full run"
  );
  let full_prov =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &full);
  assert!(
    full_prov.is_reproducible(),
    "a greedy, un-truncated run reproduces from options alone"
  );

  // WITH a callback that stops at the first non-prefill step: the decode breaks
  // early, so the transcript is a truncation of the full one.
  let stop: &(
     dyn Fn(&crate::audio::whisper::result::TranscriptionProgress) -> Option<bool> + Sync
   ) = &|_progress| Some(false);
  let truncated = TranscribeTask::new(&mock, &t)
    .with_progress_callback(stop)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(
    truncated.task_facts().early_stopped(),
    Some(true),
    "the callback's Some(false) truncated this run"
  );
  let trunc_prov =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &truncated);
  assert_eq!(
    trunc_prov.task_facts().early_stopped(),
    Some(true),
    "provenance records the early-stop outcome"
  );
  assert!(
    !trunc_prov.is_reproducible(),
    "a callback-truncated transcript is not reproducible from the record alone"
  );
  // The two runs differ ONLY in the callback, yet their records are now distinct.
  assert_ne!(
    full_prov, trunc_prov,
    "the early-stop outcome distinguishes two runs that differ only in the callback"
  );

  // F1 (codex round 6 post-consolidation). The same greedy segment that
  // `for_result` — handed the whole transcript, which POSITIVELY observed
  // not-truncated — calls reproducible is NOT reproducible through `for_segment`,
  // which is handed only the segment and structurally cannot see whether a
  // callback truncated the decode. The pre-fix constructor fabricated a
  // `not-truncated` and claimed reproducible — the exact false promise a
  // genuinely callback-truncated segment (as here) would have inherited.
  //
  // Mutation proof: make `TaskFacts::is_reproducible_under` treat an unknown
  // `early_stopped` optimistically (as `not-truncated`) and this assertion fails,
  // reading back reproducible for a record that cannot know it was un-truncated.
  let segment = full
    .segments_slice()
    .first()
    .expect("the full greedy run produced a segment");
  let seg_prov =
    crate::audio::whisper::provenance::Provenance::for_segment(&options, &compute, segment, false);
  assert!(
    !seg_prov.is_reproducible(),
    "for_segment cannot observe the truncation, so it must not promise reproducibility"
  );
  // Supplying the COMPLETE facts — via `for_result` on the un-truncated
  // transcript, which carries the observed not-truncated — is what earns the
  // promise back.
  assert!(
    full_prov.is_reproducible(),
    "the complete facts (for_result on the un-truncated run) do promise it"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn window_id_offset_is_recorded_in_the_result_and_provenance() {
  // F4b (codex round 5), now carried in the task facts' worker schedule. The
  // worker coordinate is the WORKER input to the seeded fallback ladder's
  // sub-seed derivation, so under a seed two runs at different offsets draw
  // different RNG streams and land different transcripts. A single run records it
  // as a one-element schedule `[offset]` (an explicit KNOWN coordinate, never a
  // fabricated 0), or two such runs leave byte-identical records for text that
  // genuinely differs.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let options = DecodingOptions::new();
  let compute = crate::audio::whisper::options::ComputeOptions::new();

  let worker0 = TranscribeTask::new(&mock, &t)
    .with_window_id_offset(0)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  let worker3 = TranscribeTask::new(&mock, &t)
    .with_window_id_offset(3)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(worker0.task_facts().worker_schedule(), Some([0].as_slice()));
  assert_eq!(worker3.task_facts().worker_schedule(), Some([3].as_slice()));

  let prov0 =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &worker0);
  let prov3 =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &worker3);
  assert_eq!(prov0.task_facts().worker_schedule(), Some([0].as_slice()));
  assert_eq!(prov3.task_facts().worker_schedule(), Some([3].as_slice()));
  assert_ne!(
    prov0, prov3,
    "the worker coordinate distinguishes two runs that differ only in it"
  );
}

fn one_hot(token: u32) -> Vec<f32> {
  let mut logits = vec![0.0f32; 51865];
  logits[token as usize] = 10.0;
  logits
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn window_loop_attaches_word_timings_when_enabled() {
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  // Mock with alignment rows: dims n_audio_ctx 100 -> 100-col rows; each
  // step's row peaks 10 frames (0.2 s) later than the last.
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  let script = [
    s.english_token(),
    s.transcribe_token(),
    ts(0),
    hello,
    ts(100),
    ts(100),
    s.end_token(),
  ];
  for (step, token) in script.iter().enumerate() {
    let mut row = vec![0.0f32; 100];
    row[(step + 1) * 10] = 1.0;
    mock.push_step_with_alignment(one_hot(*token), row);
  }
  let task = TranscribeTask::new(&mock, &t);
  let options = DecodingOptions::new().with_word_timestamps();
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  assert_eq!(result.segments_slice().len(), 1);
  let words = result.segments_slice()[0].words_slice();
  assert!(!words.is_empty(), "word timings attached");
  let joined: String = words.iter().map(|w| w.word()).collect();
  assert_eq!(crate::audio::whisper::text::normalized(&joined), "hello");
  for word in words {
    assert!(word.end() >= word.start());
    assert!(
      (0.0..=2.5).contains(&word.end()),
      "timings inside the window"
    );
  }
  // Segment boundary follows the last word (update heuristics ran).
  assert!((result.segments_slice()[0].end() - words.last().unwrap().end()).abs() < 1e-4);
}

/// Runs the F1 word-timestamp scenario under the given `drop_blank_audio` and
/// returns the full result. Two windows each decode speech/bare-timestamp/speech;
/// the middle segment is a zero-length wordless slice the word-timestamp filter
/// removes AFTER id allocation. Shared by the drop-ON unique-id pin, the drop-OFF
/// Swift-parity duplicate pin, and the drop-OFF allocation-span pin so all run
/// byte-identical scripting and differ only in the id-base advance and the stored
/// span.
fn word_timestamp_removed_segment_result(drop_blank_audio: bool) -> TranscriptionResult {
  let t = tiny_tokenizer();
  let s = special();
  let hello = 2425u32;
  let world = 1002u32;
  // n_audio_ctx 200 -> 200-col alignment rows; each step's peak marches 15
  // frames later so the two real words get distinct, non-zero-length timings.
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(200),
  );
  // `without_timestamps` drops the TimestampRulesFilter, so the scripted
  // timestamps are decoded verbatim (with it on, the filter masks a third
  // consecutive timestamp and no bare pair ever forms). Prompt is then
  // [SOT, en, transcribe, no_ts]; the free predictions ts(0) hello ts(25)
  // ts(25) ts(25) world ts(50) ts(50) EOT slice into three segments --
  // [hello 0-0.5s | ts(25) 0.5s (a zero-length wordless bare pair) | world
  // 0.5-1s] -- and `word_timestamps` removes the middle one after id allocation.
  let script = [
    s.english_token(),
    s.transcribe_token(),
    s.no_timestamps_token(), // step 2 (overridden anyway; no_ts is forced)
    ts(0),
    hello,
    ts(25),
    ts(25),
    ts(25),
    world,
    ts(50),
    ts(50),
    s.end_token(),
  ];
  for (step, token) in script.iter().enumerate() {
    let mut row = vec![0.0f32; 200];
    // Peaks kept near the window start so the word-timestamp end stays inside
    // the window and its seek re-anchoring does not overshoot the next window.
    row[step + 1] = 1.0;
    mock.push_step_with_alignment(one_hot(*token), row);
  }
  let task = TranscribeTask::new(&mock, &t);
  // Each window's last timestamp is ts(50) = 1.0 s, so seek advances 16_000
  // samples per window; 48_000 samples of audio therefore run exactly two
  // windows (0..16_000, 16_000..32_000; the third would need seek < 32_000).
  let options = DecodingOptions::new()
    .with_word_timestamps()
    .with_without_timestamps()
    .maybe_drop_blank_audio(drop_blank_audio);
  let result = task.run(&vec![0.1; 48_000], &options).unwrap();
  assert_eq!(mock.counters().encode_calls(), 2, "two windows decoded");
  result
}

/// The surviving segment ids of [`word_timestamp_removed_segment_result`].
fn word_timestamp_removed_segment_ids(drop_blank_audio: bool) -> Vec<usize> {
  word_timestamp_removed_segment_result(drop_blank_audio)
    .segments_slice()
    .iter()
    .map(TranscriptionSegment::id)
    .collect()
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn word_timestamps_removing_a_segment_keeps_ids_unique_and_monotonic() {
  // F2 (codex round 5) / F1 (codex round 9), the TRUE-path pin. Under
  // `drop_blank_audio` (the default, the deliberate unique-id hardening) the next
  // window ids its segments off the count the decode ALLOCATED (3), not the count
  // that SURVIVED (2) -- otherwise window 2's first survivor renumbers back onto
  // window 1's second survivor (both id 2), leaving the pipeline-local ids
  // non-unique/non-monotonic before the merge ever runs. Window 1 allocates
  // [0, 1, 2], drops the zero-length middle id 1 -> [0, 2], advancing the base by
  // ALL 3; window 2 bases at 3, allocates [3, 4, 5], drops id 4 -> [3, 5].
  //
  // Mutation proof: advance the drop-ON branch by the survivor count and these
  // ids collapse to the drop-OFF [0, 2, 2, 4], failing uniqueness/monotonicity.
  let ids = word_timestamp_removed_segment_ids(true);
  assert_eq!(
    ids,
    vec![0, 2, 3, 5],
    "survivor ids stay unique and monotonic across the removed segment (drop ON)"
  );
  let unique: std::collections::HashSet<usize> = ids.iter().copied().collect();
  assert_eq!(unique.len(), ids.len(), "no id collision across windows");
  assert!(
    ids.windows(2).all(|w| w[0] < w[1]),
    "survivor ids stay strictly monotonic"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn word_timestamps_drop_cleared_reproduces_swifts_duplicate_ids() {
  // F1 (codex round 9), the FALSE-path Swift oracle. Clearing `drop_blank_audio`
  // restores EXACT Swift parity: `findSeekPointAndSegments(allSegmentsCount:)`
  // bases each window off the running SURVIVOR total Swift appends
  // (`TranscribeTask.swift:181`), filters zero-length (`:217`), and appends only
  // survivors (`:262`). Window 1 allocates [0, 1, 2], drops the middle -> [0, 2]
  // (survivor count 2); window 2 bases at 2, allocates [2, 3, 4], drops id 3 ->
  // [2, 4] -- so id 2 DUPLICATES, byte-for-byte as Swift's do. The pre-fix code
  // advanced by the allocated count regardless of the option, yielding the
  // unique-id [0, 2, 3, 5] here and violating the exact-parity contract.
  //
  // Mutation proof: advance the drop-OFF branch by the allocated count and these
  // ids become the drop-ON [0, 2, 3, 5], failing the duplicate-id assertion.
  let ids = word_timestamp_removed_segment_ids(false);
  assert_eq!(
    ids,
    vec![0, 2, 2, 4],
    "clearing drop_blank_audio reproduces Swift's duplicate survivor ids (drop OFF)"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn word_timestamps_drop_cleared_records_all_allocated_ordinals() {
  // F3 (codex round 13, M3), the FALSE-path allocation-span pin. Clearing
  // `drop_blank_audio` bases each window off the SURVIVOR count (Swift parity, the
  // duplicate ids `[0, 2, 2, 4]`), but the STORED `decoded_span` must still be the
  // count the decode ALLOCATED, not that survivor-counting id base: two windows
  // allocate three ordinals each (`Exact(6)`), and the middle of each is filtered
  // AFTER allocation. Recording the id base fabricated `Exact(4)` — neither the
  // allocation (6) nor the survivor extent (5) — so a merge embedding those facts
  // carried a span the survivors themselves contradict.
  //
  // Mutation proof: revert the stored span to the id base
  // (`Exact(decoded_segment_span)`) and this reads back `Exact(4)`, failing the
  // span assertion while the Swift ids stay `[0, 2, 2, 4]`.
  let result = word_timestamp_removed_segment_result(false);
  assert_eq!(
    result
      .segments_slice()
      .iter()
      .map(TranscriptionSegment::id)
      .collect::<Vec<_>>(),
    vec![0, 2, 2, 4],
    "clearing drop_blank_audio keeps Swift's duplicate survivor ids (drop OFF)",
  );
  assert_eq!(
    result.task_facts().decoded_span(),
    SpanKnowledge::Exact(6),
    "the stored span is the ordinals ALLOCATED (2 windows x 3), not the survivor \
     count (4) the false-path id base advanced by",
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn word_timestamps_off_leaves_segments_wordless() {
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 32_000], &DecodingOptions::new())
    .unwrap();
  assert!(result.segments_slice()[0].words_slice().is_empty());
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn silence_skipped_window_with_word_timestamps_surfaces_a_segment_error() {
  // Self-review finding (task-5 review): the brief's insert-code comment
  // describes a silence-skipped window's `None` `current_segments`
  // becoming `Some(vec![])` under word timestamps, mirroring Swift's
  // `currentSegments ?? []`. That is not what the already-shipped
  // `add_word_timestamps` (task 4) does: called with an empty `segments`
  // slice, its prefix-take alignment always ends up zero rows (sized off
  // `segments`' own token count, independent of the real alignment
  // matrix's shape), which `find_alignment`'s DTW guard unconditionally
  // rejects as `SegmentError::InvalidAlignmentShape`. `run` therefore
  // surfaces a `TranscribeError::Segment`, not a silent empty segment
  // list — the faithful analogue of Swift's own unconditional crash on
  // the same input (`SegmentSeeker.swift:208`/`:211`'s unguarded `1...0`
  // range) as a typed, recoverable error instead of a hard process abort.
  //
  // Reached here via an explicit negative `no_speech_threshold`, since
  // `no_speech_prob` is permanently `0.0` (`decode/mod.rs`'s own
  // faithfully-ported upstream TODO) — no positive threshold, including
  // the default, can trigger the silence skip through a real decode.
  //
  // The window must COMMIT at least one alignment row, else the `hasAlignment`
  // gate (whisper #41) makes `alignment_weights` return `None`, the whole
  // word-timestamp block is skipped, and `run` succeeds with no error. That
  // gate is Swift-correct (an alignment-less model skips word timestamps
  // entirely); this test's purpose — pinning the typed analogue of Swift's
  // `1...0` crash, which presupposes an alignment-carrying window — is
  // preserved by scripting alignment rows onto the window's steps.
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  for (token, peak) in [
    (s.english_token(), 1),
    (s.transcribe_token(), 2),
    (ts(0), 3),
    (hello, 4),
    (ts(100), 5),
    (ts(100), 6),
    (s.end_token(), 7),
  ] {
    push_aligned(&mut mock, token, peak);
  }
  let task = TranscribeTask::new(&mock, &t);
  let options = DecodingOptions::new()
    .with_word_timestamps()
    .with_no_speech_threshold(-0.1)
    .maybe_logprob_threshold(None);
  let err = task.run(&vec![0.1; 32_000], &options).unwrap_err();
  assert!(
    matches!(
      err,
      TranscribeError::Segment(SegmentError::InvalidAlignmentShape(ref shape))
        if shape.rows() == 0
    ),
    "got: {err:?}"
  );
}

// ---------------------------------------------------------------------
// drop_blank_audio (coremlit issue #14)
// ---------------------------------------------------------------------

/// The BPE tokens a Whisper model samples to spell out `[BLANK_AUDIO]` for
/// silence — several ordinary text tokens, not one special token (see
/// `constants::BLANK_AUDIO_MARKER`'s doc). Encoded with the leading space
/// the real model emits, which the drop filter's Swift-whitespace trim
/// normalizes away before matching.
fn blank_audio_tokens(t: &WhisperTokenizer) -> Vec<u32> {
  t.encode(&format!(
    " {}",
    crate::audio::whisper::constants::BLANK_AUDIO_MARKER
  ))
  .unwrap()
}

/// One window decoding to nothing but `[BLANK_AUDIO]` — the scripted
/// analogue of the 5 s-of-silence pipeline golden, one segment spanning
/// <|0.00|>..<|2.00|>.
fn script_blank_audio_window(mock: &mut MockBackend, t: &WhisperTokenizer) {
  let s = special();
  let mut steps = vec![s.english_token(), s.transcribe_token(), ts(0)];
  steps.extend(blank_audio_tokens(t));
  steps.extend([ts(100), ts(100), s.end_token()]);
  mock.push_token_steps(&steps);
}

/// One window decoding to speech / `[BLANK_AUDIO]` / speech as three
/// consecutive-timestamp-delimited segments: <|0.00|>..<|1.00|> " Hello",
/// <|1.00|>..<|2.00|> " [BLANK_AUDIO]", <|2.00|>..<|3.00|> " World".
fn script_speech_blank_speech_window(mock: &mut MockBackend, t: &WhisperTokenizer) {
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let world = t.encode(" World").unwrap()[0];
  let mut steps = vec![
    s.english_token(),
    s.transcribe_token(),
    ts(0),
    hello,
    ts(50),
    ts(50),
  ];
  steps.extend(blank_audio_tokens(t));
  steps.extend([ts(100), ts(100), world, ts(150), ts(150), s.end_token()]);
  mock.push_token_steps(&steps);
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn blank_audio_segment_is_dropped_by_default() {
  // The DEFAULT path (`drop_blank_audio == true`): a window that decodes to
  // nothing but the marker collapses to a genuinely empty result — zero
  // segments AND empty text, not a segment-less transcript still carrying
  // "[BLANK_AUDIO]" in its aggregate text. Deliberately diverges from
  // Swift, which emits the marker (see the drop=false twin below).
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut mock, &t);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 32_000], &DecodingOptions::new())
    .unwrap();
  assert!(
    result.segments_slice().is_empty(),
    "got: {:?}",
    result.segments_slice()
  );
  assert_eq!(result.text(), "", "got: {:?}", result.text());
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn blank_audio_segment_is_emitted_when_drop_is_cleared() {
  // MUTATION EVIDENCE for the test above, and the exact Swift-parity escape
  // hatch: the identical script with `drop_blank_audio == false` keeps the
  // segment and reports the marker verbatim — byte-identical to the
  // behavior that predates the option.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut mock, &t);
  let task = TranscribeTask::new(&mock, &t);
  let options = DecodingOptions::new().maybe_drop_blank_audio(false);
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();
  assert_eq!(result.segments_slice().len(), 1);
  assert_eq!(
    result.text(),
    crate::audio::whisper::constants::BLANK_AUDIO_MARKER
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn blank_audio_drop_keeps_surrounding_speech_and_preserves_ids() {
  // A blank stretch BETWEEN speech: the default drops only the blank
  // segment, the speech on either side survives untouched, and the marker
  // leaves the aggregate text with it.
  //
  // The survivors KEEP THEIR ORIGINAL IDS -- [0, 2], with the gap where
  // the blank segment 1 was. A drop removes, it does not relabel: an id is
  // an ordinal decode position (`all_segments_count + segments.len()`),
  // not an index into this vec, and nothing in the crate looks a segment
  // up by one. Renumbering to a dense [0, 1] would make id 1 mean "the
  // blank" with the filter off and "World" with it on, so a consumer
  // diffing the two settings could not correlate them; the gap, by
  // contrast, is self-describing.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_speech_blank_speech_window(&mut mock, &t);
  let task = TranscribeTask::new(&mock, &t);
  let result = task
    .run(&vec![0.1; 32_000], &DecodingOptions::new())
    .unwrap();

  let segments = result.segments_slice();
  assert_eq!(
    segments.len(),
    2,
    "blank dropped, speech kept: {segments:?}"
  );
  assert_eq!(
    segments.iter().map(|s| s.id()).collect::<Vec<_>>(),
    vec![0, 2],
    "survivors keep their decoded ids; the dropped segment leaves a gap"
  );
  for segment in segments {
    assert!(
      !segment
        .text()
        .contains(crate::audio::whisper::constants::BLANK_AUDIO_MARKER),
      "no surviving segment carries the marker: {segment:?}"
    );
  }
  assert_eq!(result.text(), "Hello World", "got: {:?}", result.text());
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn blank_audio_between_speech_is_kept_when_drop_is_cleared() {
  // MUTATION EVIDENCE for the mixed case: the identical script with the
  // filter off keeps all three segments, marker included — proving the two
  // outcomes above are the option's doing and not the script's.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_speech_blank_speech_window(&mut mock, &t);
  let task = TranscribeTask::new(&mock, &t);
  let options = DecodingOptions::new().maybe_drop_blank_audio(false);
  let result = task.run(&vec![0.1; 32_000], &options).unwrap();

  assert_eq!(result.segments_slice().len(), 3);
  assert!(
    result
      .text()
      .contains(crate::audio::whisper::constants::BLANK_AUDIO_MARKER),
    "got: {:?}",
    result.text()
  );
}

// ---------------------------------------------------------------------
// drop_blank_audio x the merge join (issue #14)
// ---------------------------------------------------------------------
//
// The join rule itself lives on `merge_transcription_results_with_options`
// and is pinned against the public merge in `result::tests` (all four
// placements: interior / trailing / leading / wholly-empty, plus the
// `false` twin and the timing-sum invariance). The tests here pin the two
// PIPELINE doors that reach it: `transcribe`'s VAD branch, and a hand-folded
// `transcribe_all` batch.

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn vad_chunked_blank_audio_does_not_leave_bare_separators() {
  // END-TO-END wiring proof for C1, through `WhisperKit::transcribe`'s VAD
  // branch. Same audio as `vad_chunked_transcribe_reanchors_and_merges`
  // (three chunks), but every chunk decodes to nothing but the blank
  // marker, so the default drop empties all three. Before the fix the
  // merge joined `["", "", ""]` into TWO BARE SPACES; the transcript of a
  // silent recording must be genuinely empty.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  script_blank_audio_window(&mut mock, &t);
  let kit = WhisperKit::with_backend(mock, t);
  let mut audio = vec![0.1f32; 96_000];
  audio[32_000..35_200].fill(0.0);
  audio[64_000..67_200].fill(0.0);
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);

  let result = kit.transcribe(&audio, &options).unwrap();
  assert_eq!(
    result.text(),
    "",
    "three emptied chunks must not join into bare separators, got {:?}",
    result.text()
  );
  assert!(result.segments_slice().is_empty());
  // The chunks were MERGED, not skipped: dropping an emptied result from
  // the merge input would have taken its timings with it, and
  // `total_audio_processing_runs` sums one per decoded window per chunk.
  assert_eq!(
    result.timings().total_audio_processing_runs(),
    3.0,
    "every chunk's timings must still be in the merged sums"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn vad_chunked_blank_audio_is_joined_verbatim_when_drop_is_cleared() {
  // MUTATION EVIDENCE + the Swift-parity pin: the identical audio and
  // script with `drop_blank_audio == false` keeps all three markers and
  // joins them with the merge's own single separator, byte-for-byte as
  // before this option existed. The C1 repair above must be INERT here —
  // it is gated on `drop_blank_audio` precisely because an empty-text
  // result is reachable WITHOUT the drop (see
  // `zero_window_run_observes_no_language_in_provenance`), and the
  // merge must keep joining those as Swift does.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(48_000));
  script_blank_audio_window(&mut mock, &t);
  let kit = WhisperKit::with_backend(mock, t);
  let mut audio = vec![0.1f32; 96_000];
  audio[32_000..35_200].fill(0.0);
  audio[64_000..67_200].fill(0.0);
  let options = DecodingOptions::new()
    .with_chunking_strategy(ChunkingStrategy::Vad)
    .maybe_drop_blank_audio(false);

  let result = kit.transcribe(&audio, &options).unwrap();
  let marker = crate::audio::whisper::constants::BLANK_AUDIO_MARKER;
  assert_eq!(result.text(), format!("{marker} {marker} {marker}"));
  assert_eq!(result.segments_slice().len(), 3);
}

/// `transcribe_all` over three clips whose middle one comes back EMPTY, and
/// the batch hand-folded through the public merge — i.e. the composition a
/// consumer batching audio actually writes, and the second public door onto
/// the bare-separator defect. Both `transcribe_all` and the merge are
/// `pub`, so gating the repair on `transcribe`'s VAD branch alone left this
/// path broken under the DEFAULT options; the fix belongs in the merge, and
/// this is the test that says so.
///
/// The middle clip holds no audio, so `TranscribeTask::run` executes
/// **zero** windows and returns a no-segment, empty-text result (the
/// drop-INDEPENDENT empty pinned by
/// `zero_window_run_observes_no_language_in_provenance`). That is
/// deliberate: it makes the pair below assert the exact semantics the merge
/// promises — with `drop_blank_audio` set, *any* empty text is kept out of
/// the join, whatever emptied it.
fn short_clip_batch(
  kit: &WhisperKit<MockBackend>,
  options: &DecodingOptions,
) -> TranscriptionResult {
  let speech = vec![0.1f32; 32_000];
  let no_audio: Vec<f32> = Vec::new();
  let results = kit.transcribe_all(&[&speech, &no_audio, &speech], options);
  let results: Vec<TranscriptionResult> = results.into_iter().map(Result::unwrap).collect();
  assert_eq!(results[1].text(), "", "the middle clip runs no window");
  merge_transcription_results_with_options(&results, options)
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn transcribe_all_batch_merged_by_hand_has_no_bare_separators() {
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let kit = WhisperKit::with_backend(mock, t);

  let merged = short_clip_batch(&kit, &DecodingOptions::new());
  assert_eq!(
    merged.text(),
    "Hello Hello",
    "an empty result must not become a doubled space, got {:?}",
    merged.text()
  );
  // Merged, not skipped: the empty clip contributed no text and every clip
  // still contributed its timings.
  assert_eq!(merged.timings().total_audio_processing_runs(), 2.0);
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn transcribe_all_batch_keeps_the_bare_separator_when_the_drop_is_cleared() {
  // MUTATION EVIDENCE + the Swift-parity pin for the batch door: cleared,
  // the identical batch joins the empty text as the bare separator Swift
  // gives it. The repair is INERT under `false` — which is exactly why it
  // could not be an unconditional filter inside the merge.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let kit = WhisperKit::with_backend(mock, t);

  let options = DecodingOptions::new().maybe_drop_blank_audio(false);
  let merged = short_clip_batch(&kit, &options);
  assert_eq!(
    merged.text(),
    "Hello  Hello",
    "the bare separator must survive the cleared drop (Swift parity)"
  );
  assert_eq!(merged.timings().total_audio_processing_runs(), 2.0);
}

// ---------------------------------------------------------------------
// The unseeded-sampling invariant (coremlit issue #14, codex round 1 /
// finding 2)
// ---------------------------------------------------------------------
//
// `Provenance::is_reproducible` used to reconstruct the decode's effective
// temperature from the SURVIVING segments. Every filter between a decoded
// window and a surviving segment is lossy, so a window that sampled from an
// unseeded RNG could be erased entirely and leave a transcript that looked
// greedy — and therefore reproducible — when it was not.
//
// The fix accumulates the fact in `TranscribeTask::run`, at the one point
// where the accepted temperature is still knowable and ahead of every filter
// that could erase it. These tests drive the real pipeline into each of those
// filters and pin that the fact survives.

/// Options that make the blank window (and ONLY the blank window) fall back,
/// landing it on exactly temperature `0.2`.
///
/// The scripted speech window's decode compresses to 0.667 and the blank
/// window's to 0.952, so a `compression_ratio_threshold` of 0.8 sits between
/// them: the blank window trips the ladder on every attempt and the speech
/// window never does — under ONE shared `DecodingOptions`, exactly as
/// `WhisperKit::transcribe`'s VAD branch decodes all of its chunks. With
/// `temperature_fallback_count == 1` the ladder's last rung is
/// `0.0 + 1 * 0.2`, so the blank window is accepted at 0.2 and its segment
/// carries that temperature.
///
/// Nothing here touches the sampler's determinism: the mock's logits are
/// one-hot at 10.0, so even at 0.2 (`1/t == 5`, giving the target token a
/// softmax mass of `1 - 5e-11` inside the top-k) the draw lands on the
/// scripted token. The decode is stochastic in KIND — it consults the RNG —
/// which is the entire point; it is simply peaked enough to script.
fn blank_falls_back_to_point_two() -> DecodingOptions {
  DecodingOptions::new()
    .with_compression_ratio_threshold(0.8)
    .with_temperature_fallback_count(1)
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_window_accepted_above_zero_can_decode_the_blank_marker_and_be_dropped() {
  // THE REACHABILITY PROOF, and the exact question the review posed: can a
  // window accepted at temperature > 0 decode to exactly the blank marker
  // and then be dropped? Yes — constructed here, not argued.
  //
  // First, with the drop CLEARED, observe what the window actually decodes:
  // `[BLANK_AUDIO]`, at temperature 0.2, from an unseeded sampler.
  let t = tiny_tokenizer();
  let options = blank_falls_back_to_point_two();
  assert_eq!(options.seed(), None, "unseeded is the default");

  let mut observed_mock =
    MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut observed_mock, &t);
  let observed = TranscribeTask::new(&observed_mock, &t)
    .run(
      &vec![0.1; 32_000],
      &options.clone().maybe_drop_blank_audio(false),
    )
    .unwrap();
  assert_eq!(
    observed.text(),
    crate::audio::whisper::constants::BLANK_AUDIO_MARKER
  );
  assert_eq!(
    observed.segments_slice()[0].temperature(),
    0.2,
    "the ladder must have climbed, or this proves nothing"
  );

  // Now the same window under the DEFAULT drop: the segment is deleted, and
  // with it every trace of the temperature it was decoded at. The result has
  // nothing left to read a temperature off — and yet the decode really did
  // draw from an unseeded RNG, so the transcript is NOT reproducible.
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut mock, &t);
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();

  assert!(result.segments_slice().is_empty(), "the drop emptied it");
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(true),
    "the sampling must survive the segment that carried it"
  );

  let provenance = crate::audio::whisper::provenance::Provenance::for_result(
    &options,
    &crate::audio::whisper::options::ComputeOptions::new(),
    &result,
  );
  assert!(
    !provenance.is_reproducible(),
    "an unseeded sampled window was dropped: this transcript cannot be \
     promised byte-for-byte"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_rejected_nonzero_attempt_is_recorded_even_when_the_window_is_accepted_greedily() {
  // F2 (codex round 3), history 1. base temperature -0.2, increment 0.2,
  // fallback 1: attempt 0 runs at -0.2 and DRAWS from the RNG, is rejected on
  // its first-token logprob, and attempt 1 runs at exactly 0.0 (greedy) and is
  // accepted as the ladder's last rung. The accepted temperature is 0.0, so
  // the OLD temperature-inferred fact called this greedy and reproducible --
  // but attempt 0's unseeded draw already happened, and a re-run may keep its
  // output, so the transcript is NOT reproducible.
  //
  // `without_timestamps` empties the filter chain (no token is masked to
  // -inf), so the -0.2 attempt samples over finite logits without tripping the
  // negative-temperature/masked-token corner. Flat logits make the first-token
  // logprob ~ln(1/V) at EITHER temperature, so both attempts break at their
  // first token deterministically -- attempt 0 rejected, attempt 1 accepted as
  // the last rung -- with no probabilistic assertion.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  for _ in 0..24 {
    mock.push_step(vec![0.0f32; 51865]);
  }
  let options = DecodingOptions::new()
    .with_language("en") // no probe: keep the RNG accounting to the fallback ladder
    .with_without_timestamps()
    .with_temperature(-0.2)
    .with_temperature_fallback_count(1) // attempts: -0.2, then exactly 0.0
    .with_first_token_logprob_threshold(-1.5)
    .maybe_compression_ratio_threshold(None)
    .maybe_logprob_threshold(None);
  assert_eq!(options.seed(), None, "unseeded is the default");

  // 32_000 samples clears the 1 s (16_000-sample) window padding, so exactly
  // one window actually decodes (a shorter clip would be skipped outright).
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert!(
    mock.counters().encode_calls() > 0,
    "a window must actually decode, or this proves nothing"
  );
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(true),
    "attempt 0 drew at -0.2, even though the window was accepted greedily at 0.0"
  );
  let provenance = crate::audio::whisper::provenance::Provenance::for_result(
    &options,
    &crate::audio::whisper::options::ComputeOptions::new(),
    &result,
  );
  assert!(
    !provenance.is_reproducible(),
    "an unseeded rejected draw cannot be promised byte-for-byte"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_nonzero_temperature_that_never_samples_records_no_sampling() {
  // F2 (codex round 3), the inverse history. A non-zero temperature with
  // `sample_length == 0` runs ZERO decode iterations, so the sampler is never
  // consulted and no RNG draw happens. The OLD fact inferred sampling from the
  // non-zero temperature and wrongly claimed the transcript was sampled; the
  // drew-from-rng fact records the truth -- nothing was drawn.
  let t = tiny_tokenizer();
  let mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let options = DecodingOptions::new()
    .with_language("en") // no probe (a probe would itself draw)
    .with_without_timestamps() // lump-branch seek advance, so the window terminates cleanly
    .with_temperature(0.3) // non-zero...
    .with_sample_length(0) // ...but zero iterations, so `sample` is never called
    .with_temperature_fallback_count(0);

  // 32_000 samples clears the window padding, so the window really decodes
  // (with zero sampling iterations) rather than being skipped -- otherwise the
  // old temperature-inferred fact would never have been consulted either, and
  // the test would pass vacuously.
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert!(
    mock.counters().encode_calls() > 0,
    "the window must actually decode (at temperature 0.3) for the fact to matter"
  );
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(false),
    "a zero-iteration decode never draws, whatever the temperature -- the old \
     `temperature != 0.0` inference wrongly recorded this window as sampled"
  );

  // F3 (codex round 4). The lump-branch segment DID land at 0.3: segment
  // discovery copies the accepted rung into the segment even though ZERO
  // sampling iterations ran. This is the exact history the old
  // `for_result` OR-ed `segment.temperature() != 0.0` on, reporting a false
  // "sampled" and a false non-reproducible. `for_result` must now read only
  // the carried draw fact -- no draw, so no sampling and reproducible, despite
  // the 0.3 segment sitting right there.
  assert_eq!(
    result.segments_slice().len(),
    1,
    "the zero-iteration window still lumps into one segment"
  );
  assert_eq!(
    result.segments_slice()[0].temperature(),
    0.3,
    "the segment carries the accepted 0.3 rung, though nothing was drawn"
  );
  let provenance = crate::audio::whisper::provenance::Provenance::for_result(
    &options,
    &crate::audio::whisper::options::ComputeOptions::new(),
    &result,
  );
  assert_eq!(
    provenance.task_facts().drew_from_rng(),
    Some(false),
    "the 0.3 segment must not be read as a draw"
  );
  assert!(
    provenance.is_reproducible(),
    "a zero-iteration decode drew nothing, so it is reproducible despite the 0.3 segment"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn unseeded_sampling_survives_the_blank_audio_drop() {
  // THE FULL FAILING HISTORY, end to end through the merge every VAD-chunked
  // `WhisperKit::transcribe` runs:
  //
  //   1. chunk A decodes speech greedily at 0.0 and survives;
  //   2. chunk B falls back, is accepted at 0.2, and samples exactly
  //      `[BLANK_AUDIO]` from an unseeded RNG;
  //   3. the default blank-drop deletes chunk B's only segment;
  //   4. the merged transcript is chunk A's "Hello" — every surviving
  //      segment reads 0.0.
  //
  // BEFORE the fix, `for_result` inferred the effective temperature from
  // those survivors, saw only 0.0, and answered `is_reproducible() == true`.
  // A re-run redraws chunk B's unseeded sample, and text that is not the
  // marker SURVIVES the drop and changes the transcript — so that guarantee
  // was false.
  let t = tiny_tokenizer();
  let options = blank_falls_back_to_point_two();

  let mut speech = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_clean_window(&mut speech, t.encode(" Hello").unwrap()[0]);
  let mut blank = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut blank, &t);

  let chunk_a = TranscribeTask::new(&speech, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  let chunk_b = TranscribeTask::new(&blank, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();

  assert_eq!(
    chunk_a.segments_slice()[0].temperature(),
    0.0,
    "A is greedy"
  );
  assert_eq!(chunk_a.task_facts().drew_from_rng(), Some(false));
  assert!(chunk_b.segments_slice().is_empty(), "B was emptied");
  assert_eq!(
    chunk_b.task_facts().drew_from_rng(),
    Some(true),
    "B sampled, and said so"
  );

  let merged = crate::audio::whisper::result::merge_transcription_results_with_options(
    &[chunk_a, chunk_b],
    &options,
  );
  assert_eq!(merged.text(), "Hello");
  assert!(
    merged
      .segments_slice()
      .iter()
      .all(|segment| segment.temperature() == 0.0),
    "every SURVIVING segment is greedy — which is exactly why inferring the \
     answer from them was wrong"
  );

  // The merge OR-ed the fact out of the chunk whose segments are gone.
  assert_eq!(merged.task_facts().drew_from_rng(), Some(true));

  let compute = crate::audio::whisper::options::ComputeOptions::new();
  let provenance =
    crate::audio::whisper::provenance::Provenance::for_result(&options, &compute, &merged);
  assert_eq!(
    provenance.effective_temperature(),
    Some(0.0),
    "the surviving segments really do all say 0.0 — the fix must NOT come \
     from changing this"
  );
  assert!(
    !provenance.is_reproducible(),
    "REGRESSION: an unseeded sampled window was filtered out, and the record \
     went back to promising byte-reproducibility it cannot honor"
  );

  // The seeded twin: the very same history, replayable, so the promise is
  // real this time.
  let seeded = options.clone().with_seed(7);
  let mut speech = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_clean_window(&mut speech, t.encode(" Hello").unwrap()[0]);
  let mut blank = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut blank, &t);
  let merged_seeded = crate::audio::whisper::result::merge_transcription_results_with_options(
    &[
      TranscribeTask::new(&speech, &t)
        .run(&vec![0.1; 32_000], &seeded)
        .unwrap(),
      TranscribeTask::new(&blank, &t)
        .run(&vec![0.1; 32_000], &seeded)
        .unwrap(),
    ],
    &seeded,
  );
  assert_eq!(merged_seeded.task_facts().drew_from_rng(), Some(true));
  assert!(
    crate::audio::whisper::provenance::Provenance::for_result(&seeded, &compute, &merged_seeded)
      .is_reproducible(),
    "a seed makes the same sampled window replayable"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn unseeded_sampling_survives_a_no_speech_window_with_no_segments() {
  // SIBLING (`transcribe/mod.rs`'s no-speech `continue`): a window can
  // produce no segments at all, without any filter running, and the same
  // reasoning applies — the temperature it decoded at is nowhere in the
  // output.
  //
  // A no-speech window never falls back (`needs_fallback` short-circuits on
  // the same comparison that skips it), so the way to reach this state with
  // sampling is a non-zero BASE temperature: the very first attempt draws
  // from the sampler and is accepted as-is.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_clean_window(&mut mock, t.encode(" Hello").unwrap()[0]);
  // `no_speech_threshold(-0.1)` makes every window read as silent, and
  // clearing `logprob_threshold` stops the skip being un-set again by a
  // healthy average log probability (`segment::find_seek_point_and_segments`
  // :96-99) — the same pairing `silence_skipped_window_with_word_timestamps_
  // surfaces_a_segment_error` above needs, for the same reason.
  let options = DecodingOptions::new()
    .with_temperature(0.5)
    .with_no_speech_threshold(-0.1)
    .maybe_logprob_threshold(None);
  assert_eq!(options.seed(), None);

  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();

  assert!(
    result.segments_slice().is_empty(),
    "the no-speech window contributed nothing"
  );
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(true),
    "it still sampled at 0.5, and the record has to know"
  );
  assert!(
    !crate::audio::whisper::provenance::Provenance::for_result(
      &options,
      &crate::audio::whisper::options::ComputeOptions::new(),
      &result,
    )
    .is_reproducible()
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn a_greedy_run_stays_reproducible_through_the_drop() {
  // The other direction, so the fix is not just "always say no": an
  // ALL-GREEDY run whose every segment the blank-drop deleted is still
  // perfectly reproducible — nothing ever drew from the sampler. (The old
  // inference-from-survivors rule could not tell this apart from the case
  // above: both leave zero segments, and it guessed `false` for both.)
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  script_blank_audio_window(&mut mock, &t);
  let options = DecodingOptions::new();

  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert!(result.segments_slice().is_empty());
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(false),
    "greedy throughout: the sampler was never consulted"
  );
  assert!(
    crate::audio::whisper::provenance::Provenance::for_result(
      &options,
      &crate::audio::whisper::options::ComputeOptions::new(),
      &result,
    )
    .is_reproducible(),
    "an empty greedy transcript reproduces exactly"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn unseeded_draw_survives_an_errored_vad_chunk_drop() {
  // F3 (codex round 4), the loss path. A VAD chunk decodes at a non-zero
  // temperature (drawing from an unseeded RNG), then a later decode step
  // errors, so its whole `run` errors and `WhisperKit::transcribe`'s VAD branch
  // DROPS it. The draw fact must still reach the merged transcript:
  // `decode_with_fallback` captures it BEFORE the error can propagate, into a
  // sink the VAD branch owns across chunks. Pre-fix the errored chunk's draw
  // was read only AFTER `?`, so it vanished with the dropped chunk and the
  // empty merged result claimed a byte-reproducibility a re-run (which redraws
  // that chunk's unseeded sample, and may not error) could not honor.
  let t = tiny_tokenizer();
  let s = special();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(32_000));
  // Call 1 (position 0's sample) draws at 0.2; call 2 errors, aborting the
  // chunk after the draw already happened. `fail_on_call` counts decode_step
  // calls across resets, and there is a single chunk here, so call 2 is that
  // chunk's second step.
  mock.push_token_steps(&[2425, 1002, 2425, 1002, s.end_token()]);
  mock.fail_on_call(2);
  let kit = WhisperKit::with_backend(mock, t);
  let options = DecodingOptions::new()
    .with_chunking_strategy(ChunkingStrategy::Vad)
    .with_language("en") // no probe: keep the RNG accounting to the decode
    .with_temperature(0.2);
  assert_eq!(options.seed(), None, "unseeded is the default");

  // 40_000 samples > one 32_000-sample window -> the VAD branch; no silence in
  // the 0.1 (voiced) audio -> a single chunk of 32_000 samples. That chunk
  // clears the 16_000-sample window padding, so it decodes one window, which
  // draws (call 1) then errors (call 2) and is dropped, leaving an empty
  // merged result.
  let result = kit.transcribe(&vec![0.1; 40_000], &options).unwrap();
  assert!(
    result.segments_slice().is_empty(),
    "the errored chunk was dropped, so nothing survives"
  );
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(true),
    "the dropped chunk's unseeded draw must survive into the merged result"
  );
  assert!(
    !crate::audio::whisper::provenance::Provenance::for_result(
      &options,
      &crate::audio::whisper::options::ComputeOptions::new(),
      &result,
    )
    .is_reproducible(),
    "an unseeded draw happened (in a dropped chunk), so the transcript is not reproducible"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn probe_detection_survives_an_errored_vad_chunk_drop() {
  // F3 (codex round 5), the same loss shape as the RNG-draw sink above. A VAD
  // chunk's language probe genuinely detects Spanish (call 1), then the main
  // decode errors (call 2), so the whole `run` errors and the VAD branch DROPS
  // the chunk. The detection must still reach the merged transcript:
  // `decode_with_fallback` records it into a sink the VAD branch owns across
  // chunks BEFORE the error can propagate. Pre-fix the observation lived only in
  // the dropped chunk's discarded `run`, so the merged result read
  // `detected_language == None` -- violating that field's own contract for a run
  // that plainly observed "es".
  let t = tiny_tokenizer();
  let s = special();
  let es = t.token_to_id("<|es|>").unwrap();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(32_000));
  // Call 1 is the probe: its language-filtered argmax is <|es|>. Call 2 is the
  // main decode's first step, scripted to fail -> the chunk's whole run errors.
  mock.push_token_steps(&[es, 1002, 2425, s.end_token()]);
  mock.fail_on_call(2);
  let kit = WhisperKit::with_backend(mock, t);
  // Empty language + multilingual + detect_language -> the probe runs.
  let options = DecodingOptions::new()
    .with_chunking_strategy(ChunkingStrategy::Vad)
    .with_detect_language();

  // 40_000 samples > one 32_000-sample window -> the VAD branch; one voiced
  // chunk that probes (call 1, detects "es") then errors (call 2) and is dropped.
  let result = kit.transcribe(&vec![0.1; 40_000], &options).unwrap();
  assert!(
    result.segments_slice().is_empty(),
    "the errored chunk was dropped, so nothing survives"
  );
  assert_eq!(
    result.task_facts().observed_language(),
    Some("es"),
    "the dropped chunk's probe detection must survive into the merged result"
  );
  assert_eq!(
    crate::audio::whisper::provenance::Provenance::for_result(
      &options,
      &crate::audio::whisper::options::ComputeOptions::new(),
      &result,
    )
    .task_facts()
    .observed_language(),
    Some("es"),
    "and provenance records the detection the dropped chunk made"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn predicted_language_survives_an_errored_vad_chunk_drop() {
  // F2 (codex round 6 post-consolidation), the sibling of the probe test above
  // with NO probe. Under auto-detect a language token becomes a genuine
  // OBSERVATION the instant it is SAMPLED into the predicted region — the sampler
  // draw from that same partial attempt already survives an errored drop — but
  // the observation's STRING was only built at successful finalization, so a
  // chunk that PREDICTED `<|es|>` (rather than probing it) then errored on a
  // LATER step lost it: the merged result read `observed_language == None` for a
  // run that plainly predicted "es". The fix recognizes the token at sampling
  // time into a cell the sink reads before the error can propagate.
  //
  // Mutation proof: move the capture back to finalization — disable the
  // recognition-time `observed_language_token.set(..)` in `decode::decode_text`
  // (so the string is only built when finalization succeeds) and the
  // `Some("es")` assertions below fail, reading back `None`.
  let t = tiny_tokenizer();
  let es = t.token_to_id("<|es|>").unwrap();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(32_000));
  // NO probe. The multilingual prefill `[SOT, <|en|>, <|transcribe|>,
  // <|notimestamps|>]` is forced over calls 1-3; call 4 samples the FIRST free
  // prediction, scripted to `<|es|>` (recognized as the observation there); call
  // 5 is the next step, scripted to fail -> the chunk's whole run errors.
  mock.push_token_steps(&[2425, 2425, 2425, es]);
  mock.fail_on_call(5);
  let kit = WhisperKit::with_backend(mock, t);
  // Empty language, detect_language OFF (the prefill-coupled default), and
  // `without_timestamps` so the model freely predicts `<|es|>` at the first free
  // position (no timestamp filter masks it).
  let options = DecodingOptions::new()
    .with_chunking_strategy(ChunkingStrategy::Vad)
    .with_without_timestamps();
  assert!(
    !options.detect_language(),
    "no probe runs, so <|es|> is a PREDICTION"
  );

  // 40_000 samples > one 32_000-sample window -> the VAD branch; one voiced chunk
  // that predicts "es" (call 4) then errors (call 5) and is dropped.
  let result = kit.transcribe(&vec![0.1; 40_000], &options).unwrap();
  assert!(
    result.segments_slice().is_empty(),
    "the errored chunk was dropped, so nothing survives"
  );
  assert_eq!(
    result.task_facts().observed_language(),
    Some("es"),
    "the dropped chunk's PREDICTED language must survive into the merged result"
  );
  assert_eq!(
    crate::audio::whisper::provenance::Provenance::for_result(
      &options,
      &crate::audio::whisper::options::ComputeOptions::new(),
      &result,
    )
    .task_facts()
    .observed_language(),
    Some("es"),
    "and provenance records the prediction the dropped chunk made"
  );
}

#[test]
fn recover_vad_run_facts_carries_sink_facts_with_explicit_schedule_and_span() {
  // Round 10 refactor (extends codex round 9's F3). `recover_vad_run_facts` takes
  // the sink's error-fragile facts VERBATIM — draw, early-stop, and the run's
  // FIRST-observed language (the sink accumulated these across every chunk in
  // ingestion order, a dropped chunk's "es" included, so no later survivor can
  // overwrite it) — and sets the worker schedule and decoded span EXPLICITLY.
  // The sink's own schedule cannot be merged from the survivors without absorbing
  // them to None (F2), and its wholly-unknown span seed cannot supply the exact
  // count (round 12), so the caller hands both in explicitly: the schedule it
  // folded over all chunks, and the merged surviving result's own span.
  //
  // Mutation proof: swap the two `with_*` calls in `recover_vad_run_facts` for a
  // `merge` of a survivor-facts record and the explicit schedule/span are
  // absorbed to None under the round-10 laws.
  let sink = TaskFacts::observed_clean().with_observed_language(Some("es".into()));
  let facts = recover_vad_run_facts(sink, Some(vec![1]), SpanKnowledge::Exact(1));
  assert_eq!(
    facts.observed_language(),
    Some("es"),
    "the sink's earliest ingested language is carried, even from a dropped chunk",
  );
  assert_eq!(facts.drew_from_rng(), Some(false), "and its draw watch");
  assert_eq!(
    facts.early_stopped(),
    Some(false),
    "and its early-stop watch"
  );
  assert_eq!(
    facts.worker_schedule(),
    Some([1].as_slice()),
    "the caller-folded schedule is set explicitly, not absorbed to None",
  );
  assert_eq!(
    facts.decoded_span(),
    SpanKnowledge::Exact(1),
    "and the merged surviving result's id span, likewise",
  );
}

#[test]
fn recover_vad_run_facts_keeps_a_zero_chunk_run_clean_and_known_empty() {
  // F4 (codex round 9) + round 10 (F2), the VAD facts assembly in isolation for a
  // genuine zero-chunk run. The sink is observed_clean (Some(false)/Some(false) —
  // the run watched and saw no draw or truncation), the caller folds the schedule
  // to the known-empty Some([]) (zero chunks = zero workers OBSERVED), and passes
  // the KNOWN-empty span `Exact(0)` (a zero-chunk run KNOWS it allocated no
  // ordinals, round 12 — distinct from the wholly-unknown `AtLeast(0)`). The record
  // stays reproducible AND records a KNOWN-empty schedule, distinct from the
  // unknown None a run that cannot see its workers would carry.
  //
  // Mutation proof: pass `None` for the schedule (the pre-round-10 zero-chunk
  // value) and the known-empty assertion below fails.
  let facts = recover_vad_run_facts(
    TaskFacts::observed_clean(),
    Some(Vec::new()),
    SpanKnowledge::Exact(0),
  );
  assert_eq!(facts.drew_from_rng(), Some(false));
  assert_eq!(facts.early_stopped(), Some(false));
  assert_eq!(
    facts.decoded_span(),
    SpanKnowledge::Exact(0),
    "a zero-chunk run KNOWS it allocated no ordinals -- Exact(0), not wholly-unknown",
  );
  let known_empty: &[usize] = &[];
  assert_eq!(
    facts.worker_schedule(),
    Some(known_empty),
    "a zero-chunk run KNOWS zero workers ran -- Some([]), never unknown None",
  );
  assert!(
    facts.is_reproducible_under(false),
    "a zero-chunk run drew nothing and was truncated by nothing -- reproducible",
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn vad_run_with_zero_chunks_is_known_clean_not_unknown() {
  // F4 (codex round 9), end to end. Audio LONGER than the model window takes the
  // VAD branch, but a clip SHORTER than the chunker's 16_000-sample padding yields
  // ZERO chunks (`AudioChunker.swift`'s signed `startIndex < end - padding`
  // guard). No chunk decodes and no chunk errors, so the run KNOWS nothing
  // happened: the shared sink stays observed_clean and, with no survivors, is
  // carried verbatim rather than poisoned to unknown by the empty merge's
  // unknown() (which pre-fix left both booleans None and non-reproducible).
  let t = tiny_tokenizer();
  // window_samples 8_000 < the 16_000 padding, so a 12_000-sample clip is longer
  // than the window (VAD branch taken) yet shorter than the padding (zero chunks).
  let mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(8_000));
  let kit = WhisperKit::with_backend(mock, t);
  let options = DecodingOptions::new().with_chunking_strategy(ChunkingStrategy::Vad);
  let result = kit.transcribe(&vec![0.1; 12_000], &options).unwrap();

  assert_eq!(
    kit.backend().counters().encode_calls(),
    0,
    "no chunk decoded -- a genuine zero-chunk VAD run",
  );
  assert!(result.segments_slice().is_empty());
  assert_eq!(
    result.task_facts().drew_from_rng(),
    Some(false),
    "the run watched and POSITIVELY drew nothing",
  );
  assert_eq!(
    result.task_facts().early_stopped(),
    Some(false),
    "and was truncated by nothing",
  );
  // The run KNOWS zero workers ran: a known-empty schedule Some([]), the identity
  // of the merge law, NOT the unknown None a run that cannot see its workers
  // carries (round 10, F2). Result AND provenance carry it.
  let known_empty: &[usize] = &[];
  assert_eq!(
    result.task_facts().worker_schedule(),
    Some(known_empty),
    "a zero-chunk VAD run observed zero workers -- Some([]), never unknown None",
  );
  let provenance = crate::audio::whisper::provenance::Provenance::for_result(
    &options,
    &crate::audio::whisper::options::ComputeOptions::new(),
    &result,
  );
  assert_eq!(
    provenance.task_facts().worker_schedule(),
    Some(known_empty),
    "and provenance carries the known-empty schedule verbatim",
  );
  assert!(
    provenance.is_reproducible(),
    "a zero-chunk run did nothing to redo -- reproducible",
  );
}

// ---------------------------------------------------------------------
// LoadTimings stamping (#37.3)
// ---------------------------------------------------------------------

#[test]
fn load_timings_stamp_writes_all_seven_fields_as_seconds() {
  // Dyadic (n/8 s) millisecond durations so `as_secs_f64` and the literal
  // both land on the exact same f64 — the equality is bit-exact, not
  // tolerance-based.
  let load = LoadTimings {
    model_loading: Duration::from_millis(750),
    prewarm_load_time: Duration::from_millis(250),
    encoder_load: Duration::from_millis(125),
    decoder_load: Duration::from_millis(375),
    encoder_specialization: Duration::from_millis(625),
    decoder_specialization: Duration::from_millis(875),
    tokenizer_load_time: Duration::from_millis(500),
  };
  let mut timings = TranscriptionTimings::new();
  load.stamp(&mut timings);

  assert_eq!(timings.model_loading(), 0.75);
  assert_eq!(timings.prewarm_load_time(), 0.25);
  assert_eq!(timings.encoder_load_time(), 0.125);
  assert_eq!(timings.decoder_load_time(), 0.375);
  assert_eq!(timings.encoder_specialization_time(), 0.625);
  assert_eq!(timings.decoder_specialization_time(), 0.875);
  assert_eq!(timings.tokenizer_load_time(), 0.5);

  // The stamp touches only the seven load fields; a representative
  // compute-stage bucket the run would own is left untouched.
  assert_eq!(timings.decoding_loop(), 0.0);
}

#[test]
fn load_timings_default_stamps_all_zero() {
  // The `with_backend` (mock) path carries `LoadTimings::default()`, so its
  // stamped load fields are honestly 0.0 -- no models were loaded to time.
  let mut timings = TranscriptionTimings::new();
  LoadTimings::default().stamp(&mut timings);
  for value in [
    timings.model_loading(),
    timings.prewarm_load_time(),
    timings.encoder_load_time(),
    timings.decoder_load_time(),
    timings.encoder_specialization_time(),
    timings.decoder_specialization_time(),
    timings.tokenizer_load_time(),
  ] {
    assert_eq!(value, 0.0);
  }
}

// ---------------------------------------------------------------------
// AC-2: alignment-lifecycle parity fixtures (whisper #41, design §4)
// ---------------------------------------------------------------------

/// The `(word, start, end)` tuples of one segment, for pinning word timings.
fn seg_word_tuples(seg: &TranscriptionSegment) -> Vec<(String, f32, f32)> {
  seg
    .words_slice()
    .iter()
    .map(|w| (w.word().to_string(), w.start(), w.end()))
    .collect()
}

/// One scripted step whose logits are one-hot on `token` and whose 100-col
/// alignment row peaks (value `1.0`) at column `peak`. `peak * 0.02 s` is
/// where the DTW places that token's frame; kept `< 50` (`< 1.0 s`) so a
/// word end stays inside its 1 s window and the seek refine cannot overshoot.
fn push_aligned(mock: &mut MockBackend, token: u32, peak: usize) {
  let mut row = vec![0.0f32; 100];
  row[peak] = 1.0;
  mock.push_step_with_alignment(one_hot(token), row);
}

/// Builds the four-window shape fixture of design §4 Test A on a fresh mock
/// (continuous-script, so each window consumes the next script slice and the
/// alignment accumulator carries across windows). Returns the mock; the
/// caller pairs it with `tiny_tokenizer` audio `vec![0.1; 80_000]` (5 s ->
/// exactly four 1 s windows at seek 0/16k/32k/48k) under
/// `.with_word_timestamps().with_without_timestamps().maybe_drop_blank_audio(false)`.
///
/// Peak columns encode the discriminator: W1's `world` row (committed at row
/// 7) peaks at 30 (C_STALE), so W2 — which drops its own completing EOT row
/// (would-be row 7, peaked 45 = C_FRESH) — reads W1's stale 30 for its last
/// word's end. W3/W4 consult only fresh rows (controls).
fn four_shape_alignment_fixture(t: &WhisperTokenizer) -> MockBackend {
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let world = t.encode(" World").unwrap()[0];
  let again = t.encode(" again").unwrap()[0];
  let more = t.encode(" more").unwrap()[0];
  let alpha = t.encode(" alpha").unwrap()[0];
  let beta = t.encode(" beta").unwrap()[0];
  let gamma = t.encode(" gamma").unwrap()[0];
  let x = s.no_timestamps_token(); // last-prefill sample, discarded by forcing
  let mut mock = MockBackend::new()
    .with_dims(
      ModelDims::new()
        .with_window_samples(16_000)
        .with_n_audio_ctx(100),
    )
    .with_continuous_script();

  // W1 — noTimestampEnding (slicing), offset 0 s. Committed rows 1..9; row
  // 10 (s9/EOT, peak 30) is the completing step, dropped. `more` (row 9)
  // peaks HIGH at 40; its divergent row 10 would clip it back to `again`'s
  // column 20 if it landed (mutation A) — post-fix it is dropped so `more`
  // keeps its own peak.
  for (token, peak) in [
    (s.english_token(), 3),
    (s.transcribe_token(), 5),
    (x, 7),
    (hello, 9),
    (ts(25), 11),
    (ts(25), 13),
    (world, 30),         // C_STALE: row 7, read stale by W2's dropped EOT row
    (again, 20),         // `more`'s predecessor — the clip target column
    (more, 40),          // W1's last real word, HIGH peak
    (s.end_token(), 30), // would-be row 10, dropped (clips `more` if landed)
  ] {
    push_aligned(&mut mock, token, peak);
  }
  // W2 — lump, offset 1 s, the staleness jewel. Committed rows 1..6; row 7
  // (s16/EOT, peak 45 = C_FRESH) is the completing step, dropped -> row 7
  // keeps W1's stale peak 30. `gamma` (row 6) peaks HIGH at 40 with `beta`
  // (row 5) at 20: the stale row-7 peak 30 sits between them and CLIPS gamma
  // back to column 20 (correct), whereas the fresh 45 (> 40, mutation A) or a
  // zeroed row (mutation B) would not clip it.
  for (token, peak) in [
    (s.english_token(), 5),
    (s.transcribe_token(), 8),
    (x, 11),
    (alpha, 14),
    (beta, 20),          // gamma's predecessor — the clip target column
    (gamma, 40),         // W2's last real word, HIGH peak
    (s.end_token(), 45), // would-be row 7, dropped -> stale 30 survives
  ] {
    push_aligned(&mut mock, token, peak);
  }
  // W3 — singleTimestampEnding, offset 2 s, control (all consulted rows
  // fresh). Ends `.. world ts(50) EOT`.
  for (token, peak) in [
    (s.english_token(), 5),
    (s.transcribe_token(), 8),
    (x, 11),
    (hello, 14),
    (ts(25), 17),
    (ts(25), 19),
    (world, 22),
    (ts(50), 25),
    (s.end_token(), 48),
  ] {
    push_aligned(&mut mock, token, peak);
  }
  // W4 — consecutive ending (the JFK shape), offset 3 s, control. Ends
  // `.. hello ts(50) ts(50) EOT`.
  for (token, peak) in [
    (s.english_token(), 5),
    (s.transcribe_token(), 8),
    (x, 11),
    (hello, 14),
    (ts(50), 17),
    (ts(50), 19),
    (s.end_token(), 48),
  ] {
    push_aligned(&mut mock, token, peak);
  }
  mock
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn four_window_shapes_read_stale_and_dropped_alignment_rows() {
  // Design §4 Test A. Four windows share one continuous script and one
  // never-cleared alignment accumulator (seek 0/16k/32k/48k over 5 s). W1
  // (noTs slicing) and W2 (lump) each DROP their completing EOT row; W2 then
  // reads W1's stale row 7 (peak 30), which sits between W2's `beta` (col 20)
  // and `gamma` (col 40) and CLIPS `gamma` back to column 20. W3 (singleTs)
  // and W4 (consecutive) consult only fresh rows — controls, byte-identical
  // pre/post fix.
  //
  // Word-end literals were MEASURED post-fix, then hand-checked against the
  // DTW row-selection rule (last real word's end = the column its divergent
  // next row forces) and the three-way separation before pinning. Mutation
  // matrix (design §4; run each, the named tuple then changes):
  //   A. re-commit inside `decode_step` (revert stage/commit): W1 `more`
  //      0.8 -> 0.4 AND W2 `gamma` 1.4 -> 1.8 (both completing rows land).
  //   B. re-add `alignment.fill(0.0)` in reset: ONLY W2 `gamma` 1.4 -> 1.8
  //      (W1's row 10 was already zero; W2 loses its stale row 7).
  //   D. move the loop's commit above the completion break: same as A.
  //
  // `AlignmentGather::Complete` is named explicitly, not incidentally: it is
  // the pipeline DEFAULT (round-3 owner decision) but this pin depends on it
  // rather than merely inheriting it. This test pins which alignment ROWS the
  // accumulator hands over, and the opt-in #41 gather (`SwiftParity`) zeroes
  // the tail of the last gathered row before DTW ever sees it. At any measured
  // pitch above the column count (128 for 100 columns on the reference host)
  // that erasure lands, so the discriminating column of the last row — the
  // whole signal above — would be erased and every mutation in the matrix
  // would read the same. The opt-in gather is pinned separately by
  // `swift_parity_gather_moves_the_first_windows_end_and_the_next_seek`.
  let t = tiny_tokenizer();
  let options = DecodingOptions::new()
    .with_word_timestamps()
    .with_without_timestamps()
    .maybe_drop_blank_audio(false)
    .with_alignment_gather(AlignmentGather::Complete);
  let mock = four_shape_alignment_fixture(&t);
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 80_000], &options)
    .unwrap();
  assert_eq!(mock.counters().encode_calls(), 4, "exactly four windows");

  let segs = result.segments_slice();
  let ids: Vec<usize> = segs.iter().map(TranscriptionSegment::id).collect();
  assert_eq!(
    ids,
    vec![0, 1, 2, 3, 4, 5],
    "six segments across four windows"
  );
  let words: Vec<Vec<(String, f32, f32)>> = segs.iter().map(seg_word_tuples).collect();
  let w = |text: &str, start: f32, end: f32| (text.to_string(), start, end);

  // W1 — noTimestampEnding, offset 0, two slices. `more` (row 9, peak 40)
  // keeps its own column: its divergent row 10 is dropped (post-fix zero).
  assert_eq!(words[0], vec![w(" Hello", 0.14, 0.18)]);
  assert_eq!(
    words[1],
    vec![
      w(" World", 0.24, 0.26),
      w(" again", 0.26, 0.4),
      w(" more", 0.4, 0.8),
    ]
  );
  // W2 — lump, offset 1, the staleness jewel: `gamma` CLIPPED to `beta`'s
  // column (end 1.4, zero-length) by the stale row-7 peak 30.
  assert_eq!(
    words[2],
    vec![
      w(" alpha", 1.22, 1.28),
      w(" beta", 1.28, 1.4),
      w(" gamma", 1.4, 1.4),
    ]
  );
  // W3 — singleTimestampEnding control, offset 2 (all fresh rows).
  assert_eq!(words[3], vec![w(" Hello", 2.22, 2.28)]);
  assert_eq!(words[4], vec![w(" World", 2.38, 2.44)]);
  // W4 — consecutive-ending control (the JFK shape), offset 3.
  assert_eq!(words[5], vec![w(" Hello", 3.22, 3.28)]);

  // AC-7 determinism twin: a fresh fixture reproduces the run byte-for-byte.
  let twin = TranscribeTask::new(&four_shape_alignment_fixture(&t), &t)
    .run(&vec![0.1; 80_000], &options)
    .unwrap();
  let twin_words: Vec<Vec<(String, f32, f32)>> =
    twin.segments_slice().iter().map(seg_word_tuples).collect();
  assert_eq!(words, twin_words, "the fixture is deterministic (AC-7)");
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn cap_hit_window_drops_the_completing_row() {
  // Design §4 Test B: a 224-token-cap window. Prefill [SOT,en,transcribe,
  // no_ts] then 219 `hello` + a final `hello` whose row peaks at 49 (C_F);
  // the cap (`current_tokens.len() >= 223`) completes step T=222 with a
  // non-EOT sample, `finalize` appends EOT -> 224 tokens, lump, N=224,
  // committed rows 1..222, divergent row 223 = zero (correct) vs s222's C_F
  // (pre-fix). 223 decode steps prove the cap fired, not an EOT.
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_n_audio_ctx(100));
  push_aligned(&mut mock, s.english_token(), 3);
  push_aligned(&mut mock, s.transcribe_token(), 5);
  push_aligned(&mut mock, s.no_timestamps_token(), 7);
  // 217 `hello`s with gently rising peaks (rows 4..220), then the last real
  // `hello` HIGH at 40 (row 222) with its predecessor at 20 (row 221), so the
  // dropped divergent row 223 (s222, peak 30, between 20 and 40) would clip
  // the last word if it landed.
  for step in 3..220 {
    push_aligned(&mut mock, hello, (8 + (step - 3) / 25).min(15));
  }
  push_aligned(&mut mock, hello, 20); // s220 -> row 221 (predecessor)
  push_aligned(&mut mock, hello, 40); // s221 -> row 222 (last real word)
  push_aligned(&mut mock, hello, 30); // s222 -> row 223, completing, dropped
  // Identical tokens would trip the compression/logprob fallback and replay
  // the window; disable those thresholds so the run is a single 223-step
  // attempt and `decode_steps` reads the cap directly.
  //
  // `AlignmentGather::Complete` — the pipeline default — is REQUIRED for this
  // pin to discriminate, and is named rather than inherited so the dependency
  // is legible. At N = 224 gathered rows over 100 columns (measured pitch 128
  // on the reference host) the opt-in #41 gather's copied prefix runs dry at
  // row 175, so under `SwiftParity` rows 175..=223 — including the
  // predecessor/last-word/dropped triple this test is built on — would arrive
  // entirely zeroed and Mutation A would become invisible. That gather is
  // pinned by `swift_parity_gather_moves_the_first_windows_end_and_the_next_seek`.
  let options = DecodingOptions::new()
    .with_word_timestamps()
    .with_without_timestamps()
    .maybe_drop_blank_audio(false)
    .maybe_compression_ratio_threshold(None)
    .maybe_logprob_threshold(None)
    .maybe_first_token_logprob_threshold(None)
    .with_alignment_gather(AlignmentGather::Complete);
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 480_000], &options)
    .unwrap();
  assert_eq!(
    mock.counters().decode_steps(),
    223,
    "the 224-token cap fired (a single attempt of MAX_TOKEN_CONTEXT - 1 steps), not an EOT sample"
  );
  assert_eq!(mock.counters().encode_calls(), 1, "a single window");
  let segs = result.segments_slice();
  assert_eq!(segs.len(), 1, "one lump segment");
  let last = segs[0]
    .words_slice()
    .last()
    .expect("the cap window carries words");
  assert_eq!(last.word(), " Hello");
  // Divergent row 223 (the cap's completing step) is dropped, so the last
  // word keeps its own peak-40 column (0.8). Mutation A lands that row (peak
  // 30, between the predecessor's 20 and this word's 40) and clips it to 0.4.
  assert_eq!((last.start(), last.end()), (0.4, 0.8), "row 223 dropped");
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn zero_commit_window_skips_word_timestamps() {
  // Design §4 Test C: the hasAlignment gate. Step 0 (forced SOT input)
  // samples EOT with a scripted alignment row, so the completion break fires
  // before any commit -> `alignment_weights` is `None` -> the whole
  // word-timestamp block is skipped (TranscribeTask.swift:197-199). One
  // wordless lump segment, coarse end = 1.0 s (segment_size), NOT dropped
  // (the zero-length filter lives inside the skipped block).
  let t = tiny_tokenizer();
  let s = special();
  let mut mock = MockBackend::new().with_dims(
    ModelDims::new()
      .with_window_samples(16_000)
      .with_n_audio_ctx(100),
  );
  push_aligned(&mut mock, s.end_token(), 20); // staged, never committed
  let options = DecodingOptions::new().with_word_timestamps();
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(result.segments_slice().len(), 1, "one lump segment");
  let seg = &result.segments_slice()[0];
  assert!(
    seg.words_slice().is_empty(),
    "zero-commit window attaches no words (hasAlignment gate shut)"
  );
  // Coarse `segment_size` end (1 s window), NOT word-refined, and the segment
  // is NOT dropped (the zero-length filter lives inside the skipped block).
  //
  // Mutation C (make `alignment_weights` unconditionally `Some`) does NOT
  // fail here, and never can: a zero-commit window structurally carries zero
  // text tokens too (any appended token implies a prior non-completing step,
  // which commits a row), so even with the block running,
  // `update_segments_with_word_timings` breaks before attaching anything --
  // this lump segment is wordless either way (Fable review, whisper #41
  // follow-up). Mutation C is caught instead by the three backend-level gate
  // pins in `backend/mock/tests.rs`, which assert
  // `alignment_weights(..).is_none()` directly and fail under it:
  //   - `alignment_rows_accumulate_at_position_plus_one`
  //   - `steps_without_alignment_rows_keep_the_has_alignment_gate_shut`
  //   - `a_committed_row_survives_reset_as_stale_data`
  // ...and by `alignment_less_window_with_text_tokens_skips_word_timestamps`
  // below, whose text-bearing-but-alignment-less window DOES flip under it.
  assert_eq!((seg.start(), seg.end()), (0.0, 1.0));
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn alignment_less_window_with_text_tokens_skips_word_timestamps() {
  // The genuinely discriminating hasAlignment-gate witness (Fable review,
  // whisper #41 follow-up), companion to `zero_commit_window_skips_word_
  // timestamps` above. That test's window is structurally wordless, so
  // mutation C has nothing to attach and it cannot detect the mutation (see
  // its own doc). This window decodes REAL text (`script_clean_window`: all
  // `push_token_steps`, no `push_step_with_alignment` anywhere) but never
  // stages an alignment row on any step, so `commit_alignment_row` is a
  // no-op throughout, the `hasAlignment` gate never opens, and
  // `alignment_weights` returns `None` even though the window carries text
  // -- the real-world alignment-less-model case the gate exists for
  // (TextDecoder.swift:568,711,764-771; TranscribeTask.swift:197-199).
  //
  // Measured, not assumed (the gate was mutated in place, run, then
  // reverted -- `git diff` confirmed production code byte-identical before
  // commit): under mutation C (make `alignment_weights` unconditionally
  // `Some`), the block runs against the never-written, all-zero accumulator,
  // and the degenerate boundary it produces collapses the segment to zero
  // length, so the zero-length filter (:217-218) drops it entirely --
  // `result.segments_slice().len()` goes from 1 (a real "Hello" segment) to
  // 0. A transcribed word silently vanishes; that is the concrete failure
  // this gate prevents.
  let t = tiny_tokenizer();
  let mut mock = MockBackend::new().with_dims(ModelDims::new().with_window_samples(16_000));
  let hello = t.encode(" Hello").unwrap()[0];
  script_clean_window(&mut mock, hello);
  let options = DecodingOptions::new().with_word_timestamps();
  let result = TranscribeTask::new(&mock, &t)
    .run(&vec![0.1; 32_000], &options)
    .unwrap();
  assert_eq!(
    result.text(),
    "Hello",
    "real decoded text, unlike the zero-commit companion"
  );
  assert_eq!(result.segments_slice().len(), 1);
  let seg = &result.segments_slice()[0];
  assert!(
    seg.words_slice().is_empty(),
    "no alignment ever committed -> hasAlignment gate shut -> word-timestamp \
     block skipped"
  );
  // Coarse <|0.00|>..<|2.00|> boundary, untouched by word-refinement (which
  // never ran) -- identical to the un-word-timestamped baseline in
  // `single_window_run_produces_segments_and_text`.
  assert!((seg.start() - 0.0).abs() < 1e-4);
  assert!((seg.end() - 2.0).abs() < 1e-4);
}

#[test]
fn last_speech_timestamp_seed_divides_in_f64_above_two_pow_24() {
  // Design §2 (H5). Above 2^24 samples `previous_seek as f32` can no longer
  // hold every integer, so the pre-fix `previous_seek as f32 / SAMPLE_RATE as
  // f32` pre-rounds its numerator while the helper's f64 divide (narrowed
  // once) does not — Swift's `Float(Double(previousSeek) /
  // Double(sampleRate))` (:209).
  //
  // Seed derivation (searched, not assumed): scanning odd seeds above 2^24,
  // 16_777_219 (= 2^24 + 3) is the first where the two paths diverge.
  // 16_777_219 / 16_000 = 1048.5761875 exactly; `16_777_219 as f32` rounds to
  // 16_777_220 (nearest even at the 2-ulp gap), so the pre-fix path computes
  // 16_777_220 / 16_000 = 1048.57625 -> 1048.5763_f32, while the f64 path
  // narrows 1048.5761875 -> 1048.5762_f32.
  let seek = 16_777_219usize;
  let f64_path = last_speech_timestamp_seed(seek);
  let f32_path = seek as f32 / crate::audio::whisper::constants::SAMPLE_RATE as f32;
  assert_ne!(
    f64_path, f32_path,
    "the two divide orders diverge above 2^24"
  );
  assert_eq!(f64_path, 1048.5762_f32, "helper: f64 divide, one narrowing");
  assert_eq!(
    f32_path, 1048.5763_f32,
    "pre-fix: f32 numerator pre-rounded"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn skip_special_tokens_governs_segment_text_on_both_writer_branches() {
  // Design §3 P1: the token-leak refutation's behavioral pin. `skip_special_tokens`
  // gates BOTH segment-text writer branches — the lump write
  // (`segment/mod.rs` :146-151) and the slice write (:216-221) — so a run
  // under the flag leaves no `<|...|>` marker in any segment, while the
  // default (`false`) renders them verbatim (the issue's coremlit sample is
  // exactly that flag-clear rendering, on either implementation — never a
  // library leak). The joined `TranscriptionResult::text` is special-filtered
  // in BOTH cases (`transcribe/mod.rs` ↔ TranscribeTask.swift:304-305). The
  // four-shape fixture exercises both branches (W1/W3 slice, W2/W4 lump).
  let t = tiny_tokenizer();
  let begin = special().special_token_begin();
  let base = DecodingOptions::new()
    .with_word_timestamps()
    .with_without_timestamps()
    .maybe_drop_blank_audio(false);

  // Flag ON: no segment carries a special/timestamp marker, and each
  // segment's text is exactly the decode of its `< special_token_begin`
  // tokens.
  let on = TranscribeTask::new(&four_shape_alignment_fixture(&t), &t)
    .run(&vec![0.1; 80_000], &base.clone().with_skip_special_tokens())
    .unwrap();
  for seg in on.segments_slice() {
    assert!(
      !seg.text().contains("<|"),
      "skip_special_tokens leaves no marker: {:?}",
      seg.text()
    );
    let word_only: Vec<u32> = seg
      .tokens_slice()
      .iter()
      .copied()
      .filter(|&token| token < begin)
      .collect();
    assert_eq!(seg.text(), t.decode(&word_only, false).unwrap());
  }
  assert!(!on.text().contains("<|"), "joined transcript is clean");

  // Flag OFF (default): the markers are present in the segment text (the
  // observed "leak"), yet the joined transcript stays clean.
  let off = TranscribeTask::new(&four_shape_alignment_fixture(&t), &t)
    .run(&vec![0.1; 80_000], &base)
    .unwrap();
  assert!(
    off
      .segments_slice()
      .iter()
      .all(|seg| seg.text().contains("<|")),
    "the default renders special/timestamp markers into every segment"
  );
  assert!(
    !off.text().contains("<|"),
    "joined transcript is special-filtered regardless of the flag"
  );
}

#[test]
#[ignore = "requires local tokenizer (WHISPERKIT_TEST_MODELS)"]
fn swift_parity_gather_moves_the_first_windows_end_and_the_next_seek() {
  // whisper #41 in miniature, on the mock backend: the OPT-IN alignment gather
  // is not confined to one window's word list. In THIS fixture every link of
  // that reach moves — the final gathered row's tail moves the last word's end
  // (`SegmentSeeker.swift:642-649` hands it to the segment), that segment end
  // lands later than the standing `seek` (`:221-223`'s
  // `seek = max(seek, Int(lastSpeechTimestamp * sampleRate))`) and so replaces
  // it, and the next window therefore decodes a different slice of audio. None
  // of those links is automatic: each moves only if the one before it moved
  // something far enough, and the `max` discards a segment end that does not
  // land later. Where they all do move they compound, which is what turned a
  // 476-column tail into 984 words of edit distance and one extra window
  // across the 1417 s fixture.
  //
  // Both halves of the name are asserted, and the FIRST half is the one that
  // bounds the public doc claim: window 1 already ends somewhere else, on
  // identical audio and an identical decoded script, with `seek` 0 under both
  // gathers and no preceding window to have moved anything. The divergence
  // therefore does NOT need a cascade to appear — the cascade is only what
  // compounds it. `AlignmentGather::SwiftParity`'s "Short-form" section cites
  // this alongside `segment::tests::
  // swift_parity_gather_truncates_final_alignment_row`, which shows the same
  // thing over a single `add_word_timestamps` call with no pipeline at all.
  //
  // Shape: 100 encoder columns, a segment of 6 gathered tokens
  // (`<|startoftranscript|><|en|><|transcribe|><|0.00|> Hello<|0.80|>` — the
  // prompt rides along, `SegmentSeeker.swift:427-442`), so at the reference
  // host's measured pitch of 128 the copied prefix runs out 88 columns into
  // row 4 and never reaches row 5 at all. Rows 4 and 5 are the pair that
  // brackets the only text word, and the mock commits script step `k`'s row at
  // accumulator row `k + 1`, so they are scripted at steps 3 and 4. Row 4 pays
  // for every column past 59; row 5 has a +1.0 plateau from column 44 that
  // only the un-truncated gather can see.
  //
  // Those columns straddle a cut the opt-in gather measures on the running
  // host rather than assumes, so the fixture states the layout it was built
  // for and fails here first if this host pads differently — see
  // `segment::tests::reference_host_pitch_table`, the (ignored) probe that
  // records what that layout was. The assertions below use ONE pitch because
  // this fixture's source and destination shapes share the accumulator width;
  // where a host pitches the two heights differently, `gather_swift_rows`
  // reproduces the shifted read and the numbers below stop describing it.
  let t = tiny_tokenizer();
  let s = special();
  let hello = t.encode(" Hello").unwrap()[0];
  let cols = 100usize;
  let rows = 6usize;
  let pitch = crate::audio::whisper::segment::coreml_f16_row_pitch(rows, cols).unwrap();
  assert_eq!(
    (rows * cols).saturating_sub(4 * pitch).min(cols),
    88,
    "this host measured a Float16 row pitch of {pitch} for {cols} columns; the reference \
     host's 128 is what puts the gather's cut inside row 4 and past row 5, which is the \
     whole discriminating shape of this fixture"
  );
  assert_eq!(
    (rows * cols).saturating_sub(5 * pitch).min(cols),
    0,
    "row 5 must be gathered entirely blank under `SwiftParity`"
  );

  let run = |gather| {
    let mut mock = MockBackend::new().with_dims(
      ModelDims::new()
        .with_window_samples(16_000)
        .with_n_audio_ctx(cols),
    );
    let script = [
      s.english_token(),
      s.transcribe_token(),
      ts(0),
      hello,
      ts(40),
      ts(40),
      s.end_token(),
    ];
    for (step, token) in script.iter().enumerate() {
      let row: Vec<f32> = (0..cols)
        .map(|column| match step {
          3 if column < 60 => 0.5,
          3 => -0.1,
          4 if column >= 44 => 1.0,
          _ => 0.0,
        })
        .collect();
      mock.push_step_with_alignment(one_hot(*token), row);
    }
    let task = TranscribeTask::new(&mock, &t);
    let options = DecodingOptions::new()
      .with_word_timestamps()
      .with_alignment_gather(gather);
    // 3 s of audio: how far it gets is itself an output here, so the window
    // count is not scripted but observed.
    let result = task.run(&vec![0.1; 48_000], &options).unwrap();
    let seeks: Vec<usize> = result
      .segments_slice()
      .iter()
      .map(TranscriptionSegment::seek)
      .collect();
    let ends: Vec<f32> = result
      .segments_slice()
      .iter()
      .map(TranscriptionSegment::end)
      .collect();
    (mock.counters().encode_calls(), seeks, ends)
  };

  let (complete_windows, complete_seeks, complete_ends) = run(AlignmentGather::Complete);
  let (parity_windows, parity_seeks, parity_ends) = run(AlignmentGather::SwiftParity);

  // Window 1 is identical audio and an identical script under both gathers,
  // and still ends somewhere else.
  assert_eq!(
    complete_ends[0], 0.88,
    "row 5's plateau ends window 1 at col 44"
  );
  assert_eq!(
    parity_ends[0], 1.18,
    "with row 5 blank, row 4 holds it to col 59"
  );

  // ... so window 2 starts somewhere else. THE assertion: the next window's
  // seek is a function of the gather.
  assert_eq!(complete_seeks[1], 14_080, "0.88 s * 16 kHz");
  assert_eq!(parity_seeks[1], 18_880, "1.18 s * 16 kHz");
  assert_ne!(complete_seeks[1], parity_seeks[1]);

  // ... and the drift compounds: the un-truncated gather advances in smaller
  // steps and fits one more window into the same 3 s, exactly as the port did
  // against Swift's 51 windows before #41.
  assert_eq!((complete_windows, parity_windows), (3, 2));
  assert_eq!(complete_seeks, vec![0, 14_080, 28_160]);
  assert_eq!(parity_seeks, vec![0, 18_880]);
}

// ---------------------------------------------------------------------
// A clip under the window padding decodes one window (mediagraph#536)
// ---------------------------------------------------------------------

/// How many windows `run`'s seek loop opens over `clip`, with every window
/// advancing the seek by `advance` samples (or to the clip's end, whichever
/// comes first) — `opens_window` driven exactly as the loop drives it.
fn windows_opened(clip: (usize, usize), advance: usize, window_padding: usize) -> usize {
  let (start, end) = clip;
  let mut seek = start;
  let mut first = true;
  let mut windows = 0;
  while opens_window(seek, end, window_padding, first) {
    first = false;
    windows += 1;
    seek += advance.min(end - seek);
  }
  windows
}

/// **Every non-empty clip opens a window; the padding still guards the
/// rest.** A clip table in the shapes mediagraph#536 measured, under the
/// default 1 s padding and 3 s of advance per window: each clip under the
/// padding — which Swift's guard refused whole — opens exactly one, a clip
/// of zero length opens none, and a long clip's last sliver inside the
/// padding is still left alone.
#[test]
fn every_non_empty_clip_opens_a_window_and_the_padding_still_guards_the_rest() {
  const PADDING: usize = 16_000;
  const ADVANCE: usize = 48_000;
  let table = [
    // (clip, windows opened, what Swift's guard opened)
    ((8_000, 14_400), 1, 0),    // a 0.4 s word
    ((30_000, 42_000), 1, 0),   // a 0.75 s word
    ((100_000, 116_000), 1, 0), // exactly the padding
    ((0, 6_400), 1, 0),         // ends inside the audio's first second
    ((60_000, 84_800), 1, 1),   // a 1.55 s control: one window covers it
    ((90_000, 90_000), 0, 0),   // zero length: still skipped
    ((200_000, 299_200), 2, 2), // 6.2 s: the last 0.2 s sliver stays skipped
    ((400_000, 536_000), 3, 3), // 8.5 s: three windows, as before
  ];
  for (clip, windows, swift) in table {
    assert_eq!(
      windows_opened(clip, ADVANCE, PADDING),
      windows,
      "clip {clip:?} (Swift's guard opened {swift})"
    );
  }
}

/// The special-token boundary the clip-back fixtures speak: ids at or
/// above it are special (`<|startoftranscript|>`, timestamps, …), ids
/// below are text.
const SPECIAL: u32 = 1_000;

/// The fixtures' `<|0.00|>`: `TIME + n` is the timestamp `n × 0.02` s from
/// the window's start, so `SPECIAL + 22` is `0.40`.
const TIME: u32 = SPECIAL + 2;

/// A fixture decoder: each text id `n` reads as the letter `n` names
/// (`1` is `a`), each special id as `<n>`.
fn letters(ids: &[u32]) -> Result<String, TokenizerError> {
  Ok(
    ids
      .iter()
      .map(|&id| {
        if id < SPECIAL {
          char::from(b'a' + (id as u8 - 1)).to_string()
        } else {
          format!("<{id}>")
        }
      })
      .collect(),
  )
}

/// A visible word over text ids `tokens`, timed `start..end`.
fn word(tokens: &[u32], start: f32, end: f32) -> crate::audio::whisper::result::WordTiming {
  crate::audio::whisper::result::WordTiming::new("w", tokens.to_vec(), start, end, 0.5)
}

/// A raw word of the window's alignment over its segment's tokens `span`,
/// timed `start..end` in seconds from the window's start — kept, as the
/// alignment keeps it, in the window's own samples.
fn raw(span: (usize, usize), start: f32, end: f32) -> RawWord {
  let samples = |seconds: f32| (f64::from(seconds) * 16_000.0).round() as usize;
  RawWord::new(span, samples(start), samples(end))
}

/// A segment holding `tokens` (with a log probability each), timed
/// `start..end`, carrying the visible `words`.
fn timed_segment(
  tokens: &[u32],
  start: f32,
  end: f32,
  words: Vec<crate::audio::whisper::result::WordTiming>,
) -> TranscriptionSegment {
  TranscriptionSegment::new()
    .with_start(start)
    .with_end(end)
    .with_text(letters(tokens).expect("the fixture decodes"))
    .with_tokens(tokens.to_vec())
    .with_token_log_probs(
      tokens
        .iter()
        .map(|&token| (token, -(token as f32) / 100.0))
        .collect::<Vec<_>>(),
    )
    .with_words(words)
}

/// Clip-back over the window at `seek` holding `samples` of clip, each
/// segment with its raw words, the special tokens shown (or not) in the
/// text: every kept segment, with the raw words it kept.
fn kept_showing(
  segments: Vec<(TranscriptionSegment, Vec<RawWord>)>,
  seek: usize,
  samples: usize,
  skip_special_tokens: bool,
) -> Vec<crate::audio::whisper::segment::KeptSegment> {
  let (segments, attribution): (Vec<_>, Vec<_>) = segments.into_iter().unzip();
  clip_back_to_window(
    segments,
    &attribution,
    (seek, samples),
    (SPECIAL, TIME),
    skip_special_tokens,
    letters,
  )
  .expect("the fixture decodes")
}

/// [`kept_showing`]'s segments alone.
fn clipped_showing(
  segments: Vec<(TranscriptionSegment, Vec<RawWord>)>,
  seek: usize,
  samples: usize,
  skip_special_tokens: bool,
) -> Vec<TranscriptionSegment> {
  kept_showing(segments, seek, samples, skip_special_tokens)
    .into_iter()
    .map(|(segment, _, _)| segment)
    .collect()
}

/// [`kept_showing`] with the special tokens kept in the text.
fn kept(
  segments: Vec<(TranscriptionSegment, Vec<RawWord>)>,
  seek: usize,
  samples: usize,
) -> Vec<crate::audio::whisper::segment::KeptSegment> {
  kept_showing(segments, seek, samples, false)
}

/// The spans of the raw words a kept segment kept.
fn spans(raw: &[RawWord]) -> Vec<(usize, usize)> {
  raw.iter().map(RawWord::span).collect()
}

/// [`clipped_showing`] with the special tokens kept in the text.
fn clipped(
  segments: Vec<(TranscriptionSegment, Vec<RawWord>)>,
  seek: usize,
  samples: usize,
) -> Vec<TranscriptionSegment> {
  clipped_showing(segments, seek, samples, false)
}

/// **The padded window's segments are clipped back to the clip.** Over a
/// 0.4 s clip (6 400 samples): a segment with no raw words that runs 0.6 s
/// into the padding keeps its text only up to its last timestamp inside the
/// clip and ends at the clip's end; one with no timestamp inside the clip
/// at all keeps no text and is dropped; a segment inside the clip, its text
/// closed there, is untouched; a segment that starts at the clip's end —
/// wholly in the padding — is dropped.
#[test]
fn a_padded_windows_segments_are_clipped_back_to_its_clip() {
  let clip = clipped(
    vec![
      (
        timed_segment(&[TIME, 1, TIME + 10, 2, TIME + 50], 0.0, 1.0, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[SPECIAL + 1, 1, 2], 0.0, 1.0, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[TIME + 5, 3, TIME + 15], 0.1, 0.3, Vec::new()),
        Vec::new(),
      ),
      (timed_segment(&[4], 0.4, 1.2, Vec::new()), Vec::new()),
    ],
    0,
    6_400,
  );
  let spans: Vec<(f32, f32)> = clip.iter().map(|s| (s.start(), s.end())).collect();
  assert_eq!(
    spans.len(),
    2,
    "the unplaceable segment and the one wholly in the padding are dropped"
  );
  assert_eq!(spans[0].0, 0.0);
  assert!((spans[0].1 - 0.4).abs() < 1e-6, "cut at the clip's end");
  assert_eq!(clip[0].tokens_slice(), &[TIME, 1, TIME + 10, TIME + 20]);
  assert_eq!(
    clip[0].text(),
    "<1002>a<1012><1022>",
    "with no raw words, the text up to the last timestamp inside the clip"
  );
  assert_eq!(spans[1], (0.1, 0.3));
  assert_eq!(clip[1].tokens_slice(), &[TIME + 5, 3, TIME + 15]);
}

/// **The clip-back answers where each token it kept sat in its window**
/// (Codex R7 row 3): the positions among the window's tokens flattened
/// across every segment, the dropped ones included — what the visible words
/// are aligned over. The first segment keeps all but its cut `2`, the
/// second and fourth go, and the third keeps its three tokens, eight on.
#[test]
fn the_clip_back_answers_where_each_kept_token_sat_in_its_window() {
  let clip = kept(
    vec![
      (
        timed_segment(&[TIME, 1, TIME + 10, 2, TIME + 50], 0.0, 1.0, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[SPECIAL + 1, 1, 2], 0.0, 1.0, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[TIME + 5, 3, TIME + 15], 0.1, 0.3, Vec::new()),
        Vec::new(),
      ),
      (timed_segment(&[4], 0.4, 1.2, Vec::new()), Vec::new()),
    ],
    0,
    6_400,
  );
  let survivors: Vec<&[usize]> = clip
    .iter()
    .map(|(_, _, positions)| positions.as_slice())
    .collect();
  assert_eq!(
    survivors,
    [&[0, 1, 2, 4][..], &[8, 9, 10][..]],
    "each kept token's position in the window"
  );
  for (segment, _, positions) in &clip {
    assert_eq!(
      positions.len(),
      segment.tokens_slice().len(),
      "one position per kept token"
    );
  }
}

/// LAW (Codex R1): inclusion is decided in samples, never by comparing
/// independently rounded seconds. A segment the model started at timestamp
/// token 20 starts at `20 × 0.02 = 0.39999998` s, a 6 400-sample clip ends
/// at `0.40000001` s — so in seconds it looked inside the clip, and in
/// samples it starts exactly at the clip's end and is dropped. The same
/// holds an hour into the audio, where the f32 seconds carry a dozen
/// samples' worth of rounding.
#[test]
fn a_segment_starting_at_the_clip_end_is_dropped_in_samples() {
  for seek in [0usize, 57_600_000] {
    let (window_start, clip_end) = crate::audio::whisper::segment::window_span(seek, 6_400);
    let at_end = window_start + 20.0 * crate::audio::whisper::constants::SECONDS_PER_TIME_TOKEN;
    let before_end = window_start + 19.0 * crate::audio::whisper::constants::SECONDS_PER_TIME_TOKEN;
    let clip = clipped(
      vec![
        (
          timed_segment(&[TIME, 1, TIME + 19], window_start, before_end, Vec::new()),
          Vec::new(),
        ),
        (
          timed_segment(&[2], at_end, clip_end + 0.5, Vec::new()),
          Vec::new(),
        ),
      ],
      seek,
      6_400,
    );
    assert_eq!(
      clip.len(),
      1,
      "seek {seek}: the segment at token 20 starts at the clip's end"
    );
    assert_eq!(clip[0].tokens_slice(), &[TIME, 1, TIME + 19]);
  }
}

/// LAW (Codex R1, R5): a word the alignment placed wholly in the padding is
/// removed from its segment — its tokens, their log probabilities and its
/// text with it — rather than clamped to a zero-length word whose text the
/// transcript would still carry: the raw word cuts the text at its span,
/// and is not among the raw words its segment keeps — from which the
/// visible words are derived. A word that crosses the clip's end began in
/// the clip's audio, and stays; a segment left with no text is dropped.
#[test]
fn a_word_in_the_padding_leaves_its_segment_and_the_segment_is_rebuilt() {
  // <sot> <ts0> a b c d <ts50> — words: "ab" 0.0-0.25, "c" 0.3-0.45
  // (crosses the 0.4 s end), "d" 0.6-0.8 (wholly in the padding).
  let segment = timed_segment(
    &[SPECIAL + 1, SPECIAL + 2, 1, 2, 3, 4, SPECIAL + 52],
    0.0,
    1.0,
    vec![
      word(&[1, 2], 0.0, 0.25),
      word(&[3], 0.3, 0.45),
      word(&[4], 0.6, 0.8),
    ],
  );
  let segment_raw = vec![
    raw((2, 4), 0.0, 0.25),
    raw((4, 5), 0.3, 0.45),
    raw((5, 6), 0.6, 0.8),
  ];
  // A segment whose every word is in the padding, though it starts inside.
  let all_padding = timed_segment(&[5], 0.38, 0.9, vec![word(&[5], 0.5, 0.9)]);
  let all_padding_raw = vec![raw((0, 1), 0.5, 0.9)];
  // A segment whose last word the alignment squeezed to no length at the
  // clip's very end: it holds none of the padding, and stays.
  let squeezed = timed_segment(
    &[6, 7],
    0.1,
    0.4,
    vec![word(&[6], 0.1, 0.3), word(&[7], 0.4, 0.4)],
  );
  let squeezed_raw = vec![raw((0, 1), 0.1, 0.3), raw((1, 2), 0.4, 0.4)];
  let clip = kept(
    vec![
      (segment, segment_raw),
      (all_padding, all_padding_raw),
      (squeezed, squeezed_raw),
    ],
    0,
    6_400,
  );

  assert_eq!(clip.len(), 2, "the all-padding segment is dropped");
  assert_eq!(
    clip[1].0.tokens_slice(),
    &[6, 7],
    "a word of no length at the end stays"
  );
  assert_eq!(
    spans(&clip[1].1),
    [(0, 1), (1, 2)],
    "both its raw words kept"
  );
  assert_eq!(
    spans(&clip[0].1),
    [(2, 4), (4, 5)],
    "the crossing word kept, the padding word gone"
  );
  let kept = &clip[0].0;
  assert_eq!(
    kept.tokens_slice(),
    &[SPECIAL + 1, SPECIAL + 2, 1, 2, 3, TIME + 20],
    "the end boundary states the clamped span (R2)"
  );
  assert_eq!(
    kept
      .token_log_probs_slice()
      .iter()
      .map(|&(token, _)| token)
      .collect::<Vec<_>>(),
    vec![SPECIAL + 1, SPECIAL + 2, 1, 2, 3, SPECIAL + 52],
    "the log probabilities follow their tokens; the rewritten step keeps what was sampled"
  );
  assert_eq!(kept.text(), "<1001><1002>abc<1022>");
  assert!(
    kept.words_slice().is_empty(),
    "no visible word is the clip-back's to keep"
  );

  // With special tokens skipped, the rebuilt text is the kept words alone.
  let segment = timed_segment(
    &[SPECIAL + 1, 1, 2, 4],
    0.0,
    1.0,
    vec![word(&[1, 2], 0.0, 0.2), word(&[4], 0.5, 0.7)],
  );
  let clip = clipped_showing(
    vec![(segment, vec![raw((1, 3), 0.0, 0.2), raw((3, 4), 0.5, 0.7)])],
    0,
    6_400,
    true,
  );
  assert_eq!(clip[0].text(), "ab");
}

/// LAW (Codex R2, partial coverage): a word in the padding is removed even
/// where the raw words do not cover the segment's text. A three-token
/// segment given two raw words — the first inside the clip, the second
/// wholly in the padding — keeps the first word's token and nothing after
/// it: the padding word's token and the token no word covered go, and so
/// do their log probabilities and their text.
#[test]
fn a_padding_word_goes_even_when_the_words_do_not_cover_the_text() {
  let short = timed_segment(
    &[TIME, 1, 2, 3, TIME + 15],
    0.0,
    0.3,
    vec![word(&[1], 0.0, 0.2), word(&[2], 0.45, 0.6)],
  );
  let kept = kept(
    vec![(short, vec![raw((1, 2), 0.0, 0.2), raw((2, 3), 0.45, 0.6)])],
    0,
    6_400,
  );
  assert_eq!(spans(&kept[0].1), [(1, 2)], "the padding word is not kept");
  let clip: Vec<TranscriptionSegment> = kept.into_iter().map(|(segment, _, _)| segment).collect();

  assert_eq!(clip.len(), 1);
  assert_eq!(clip[0].tokens_slice(), &[TIME, 1, TIME + 15]);
  assert_eq!(
    clip[0]
      .token_log_probs_slice()
      .iter()
      .map(|&(token, _)| token)
      .collect::<Vec<_>>(),
    vec![TIME, 1, TIME + 15]
  );
  assert_eq!(clip[0].text(), "<1002>a<1017>");
}

/// LAW (Codex R2, the 10 ms grid): an aligned word is read at the sample it
/// states, never snapped to the 20 ms token grid. In a 6 320-sample clip
/// (0.395 s) a word at 0.39–0.40 s starts at sample 6 240 and crosses the
/// clip's end, so it is kept, cut at the end — at the start of the audio
/// and an hour into it.
#[test]
fn a_word_on_the_ten_millisecond_grid_that_crosses_the_end_is_kept() {
  for seek in [0usize, 57_600_000] {
    let (window_start, clip_end) = crate::audio::whisper::segment::window_span(seek, 6_320);
    let segment = timed_segment(
      &[1, 2],
      window_start,
      window_start + 0.4,
      vec![
        word(&[1], window_start, window_start + 0.2),
        word(&[2], window_start + 0.39, window_start + 0.4),
      ],
    );
    let clip = kept(
      vec![(segment, vec![raw((0, 1), 0.0, 0.2), raw((1, 2), 0.39, 0.4)])],
      seek,
      6_320,
    );
    assert_eq!(clip.len(), 1, "seek {seek}");
    assert_eq!(
      spans(&clip[0].1),
      [(0, 1), (1, 2)],
      "seek {seek}: the boundary word is kept"
    );
    assert_eq!(clip[0].0.text(), "ab", "seek {seek}");
    assert!(
      (clip[0].0.end() - clip_end).abs() < 1e-3,
      "seek {seek}: and the segment ends at the clip's end"
    );
  }
}

/// LAW (Codex R2, stale boundaries): every timestamp token a kept segment
/// carries past the clip's end is rewritten to the last 20 ms step at or
/// before the end, on a rebuilt segment and on one kept whole for want of
/// raw words — so `[<0.00>, a, b, <1.00>]` cut to 0.4 s reads
/// `[<0.00>, a, <0.40>]`, and its text says so when special tokens are
/// shown. The rewritten step's log-probability pair keeps the token the
/// model sampled there: no probability is attributed to the rewritten one.
#[test]
fn a_kept_segment_states_its_clamped_span_in_its_timestamp_tokens() {
  let rebuilt = timed_segment(
    &[TIME, 1, 2, TIME + 50],
    0.0,
    1.0,
    vec![word(&[1], 0.0, 0.3), word(&[2], 0.5, 0.9)],
  );
  let rebuilt_raw = vec![raw((1, 2), 0.0, 0.3), raw((2, 3), 0.5, 0.9)];
  let whole = timed_segment(&[TIME + 5, 3, TIME + 10, TIME + 40], 0.1, 0.8, Vec::new());
  let clip = clipped(vec![(rebuilt, rebuilt_raw), (whole, Vec::new())], 0, 6_320);

  assert_eq!(clip.len(), 2);
  assert_eq!(clip[0].tokens_slice(), &[TIME, 1, TIME + 19]);
  assert_eq!(
    clip[0].token_log_probs_slice(),
    &[
      (TIME, -(TIME as f32) / 100.0),
      (1, -0.01),
      (TIME + 50, -((TIME + 50) as f32) / 100.0)
    ],
    "the rewritten step keeps the pair that was sampled"
  );
  assert_eq!(clip[0].text(), "<1002>a<1021>");
  assert_eq!(clip[1].tokens_slice(), &[TIME + 5, 3, TIME + 10, TIME + 19]);
  assert_eq!(
    clip[1].text(),
    "<1007>c<1012><1021>",
    "its text up to its last timestamp inside, and its end restated"
  );

  // Special tokens skipped: the text never showed the boundary.
  let whole = timed_segment(&[TIME + 5, 3, TIME + 10, TIME + 40], 0.1, 0.8, Vec::new());
  let clip = clipped_showing(vec![(whole, Vec::new())], 0, 6_320, true);
  assert_eq!(clip[0].tokens_slice(), &[TIME + 5, 3, TIME + 10, TIME + 19]);
  assert_eq!(clip[0].text(), "c");
}

/// LAW (Codex R3, R5): **the cut falls at the raw word's position, and the
/// visible list's merging plays no part.** Swift's `mergePunctuations`
/// walks the original pairs, so `A ! ! B` merges `A!` and then replaces it
/// with `!!` — `A` is gone from the visible word list. The raw words still
/// hold `A`, `!`, `!` and `B`, each with its span: `B` lies in the padding,
/// so the cut keeps `A ! !` and drops `B`, and the visible list, Swift's,
/// loses `B`.
#[test]
fn the_cut_falls_at_the_raw_words_position_whatever_the_merge_dropped() {
  use crate::audio::whisper::{
    constants::{APPEND_PUNCTUATION, PREPEND_PUNCTUATION},
    result::WordTiming,
    segment::merge_punctuations,
  };
  let bang = 9u32;
  let aligned = [
    WordTiming::new(" A", vec![1], 0.0, 0.1, 0.9),
    WordTiming::new("!", vec![bang], 0.1, 0.15, 0.9),
    WordTiming::new("!", vec![bang], 0.15, 0.2, 0.9),
    WordTiming::new(" B", vec![2], 0.5, 0.7, 0.9),
  ];
  let visible = merge_punctuations(&aligned, PREPEND_PUNCTUATION, APPEND_PUNCTUATION);
  let visible_words: Vec<&str> = visible.iter().map(WordTiming::word).collect();
  assert_eq!(visible_words, ["!!", " B"], "Swift's merge drops `A`");

  let segment = timed_segment(&[TIME, 1, bang, bang, 2, TIME + 50], 0.0, 1.0, visible);
  let clip = kept(
    vec![(
      segment,
      vec![
        raw((1, 2), 0.0, 0.1),
        raw((2, 3), 0.1, 0.15),
        raw((3, 4), 0.15, 0.2),
        raw((4, 5), 0.5, 0.7),
      ],
    )],
    0,
    6_400,
  );
  assert_eq!(clip.len(), 1, "the segment is kept");
  assert_eq!(clip[0].0.tokens_slice(), &[TIME, 1, bang, bang, TIME + 20]);
  assert_eq!(
    spans(&clip[0].1),
    [(1, 2), (2, 3), (3, 4)],
    "`A ! !` kept, the padding word gone"
  );
}

/// LAW (Codex R3, the first timestamp past the end; restated in R7 row 4):
/// **no timestamp is left outside the clip.** A segment whose first
/// timestamp already states a time past a 0.395 s clip — a lump at the
/// window's start, or a DTW re-timing — keeps its own bounds, 0.00 s to the
/// clip's end, and its boundary timestamps state them: the first restated at
/// 0.00 s, the last at the clip's last 20 ms step — neither kept at 0.40 s
/// or more.
#[test]
fn no_timestamp_is_left_outside_the_clip() {
  let lump = timed_segment(
    &[TIME + 20, 3, TIME + 25],
    0.0,
    0.5,
    vec![word(&[3], 0.1, 0.3)],
  );
  let clip = clipped(vec![(lump, vec![raw((1, 2), 0.1, 0.3)])], 0, 6_320);
  assert_eq!(clip.len(), 1);
  assert_eq!(clip[0].tokens_slice(), &[TIME, 3, TIME + 19]);
  assert_eq!(clip[0].text(), "<1002>c<1021>");
  assert_eq!(clip[0].start(), 0.0, "the start its first timestamp states");
}

/// LAW (Codex R7 row 4, [medium]): **the bounds are decided before the
/// timestamps are restated, and the tokens state them.** A 0.5 s clip whose
/// segment the model read as `<|0.80|> c <|1.00|>`, its bounds wholly in the
/// padding, its one raw word at 0.10–0.20 inside the clip: the segment takes
/// its bounds from that word, and its boundary timestamps restate them at
/// their 20 ms steps — `<|0.10|> c <|0.20|>` — where restating each
/// past-the-end timestamp at the clip's end first gave `<|0.50|> c <|0.50|>`
/// beside fields of 0.10–0.20. A timestamp inside the text that states no
/// time of the span it keeps — `<|0.90|>` in `<|0.80|> c <|0.90|> d
/// <|1.00|>`, the text kept from 0.10 to 0.30 — is removed, its log
/// probability with it, rather than left contradicting it.
#[test]
fn the_timestamps_state_the_bounds_the_segment_keeps() {
  let lump = timed_segment(&[TIME + 40, 3, TIME + 50], 0.8, 1.0, Vec::new());
  let clip = clipped(vec![(lump, vec![raw((1, 2), 0.1, 0.2)])], 0, 8_000);
  assert_eq!(clip.len(), 1);
  assert_eq!(
    clip[0].tokens_slice(),
    &[TIME + 5, 3, TIME + 10],
    "the bounds' own 20 ms steps"
  );
  assert!(
    (clip[0].start() - 0.1).abs() < 1e-6 && (clip[0].end() - 0.2).abs() < 1e-6,
    "the fields the tokens state: {}..{}",
    clip[0].start(),
    clip[0].end()
  );
  assert_eq!(clip[0].text(), "<1007>c<1012>");

  let inner = timed_segment(
    &[TIME + 40, 3, TIME + 45, 4, TIME + 50],
    0.8,
    1.0,
    Vec::new(),
  );
  let clip = clipped(
    vec![(inner, vec![raw((1, 2), 0.1, 0.2), raw((3, 4), 0.25, 0.3)])],
    0,
    8_000,
  );
  assert_eq!(clip.len(), 1);
  assert_eq!(
    clip[0].tokens_slice(),
    &[TIME + 5, 3, 4, TIME + 15],
    "the inner timestamp past the span is removed"
  );
  assert_eq!(
    clip[0].token_log_probs_slice(),
    &[
      (TIME + 40, -((TIME + 40) as f32) / 100.0),
      (3, -0.03),
      (4, -0.04),
      (TIME + 50, -((TIME + 50) as f32) / 100.0)
    ],
    "the removed timestamp takes its pair; a restated one keeps what was sampled"
  );
  assert_eq!(clip[0].text(), "<1007>cd<1017>");
}

/// LAW (Codex R11, [medium]): **a reversed segment is found on the bounds it
/// arrives with, before they are clamped into the clip.** A 0.5 s clip whose
/// segment the model read as `<|0.60|> c <|0.50|>` — out of order, which
/// `without_timestamps` does not filter — its one raw word at 0.10–0.20: the
/// segment is retimed from that word, `<|0.10|> c <|0.20|>`, 0.10–0.20.
/// Clamped first, its bounds read 0.50–0.50, in order, and the text stayed
/// there, at no length, both timestamps stating 0.50. A raw word that
/// crosses the clip's end retimes the segment to its own start and the
/// clip's end: the retimed bounds are clamped after. And a reversed segment
/// no raw word attributes, `<|0.40|> c <|0.20|>`, is dropped: nothing
/// places its text.
#[test]
fn a_reversed_segment_is_found_before_its_bounds_are_clamped() {
  let reversed = || timed_segment(&[TIME + 30, 3, TIME + 25], 0.6, 0.5, Vec::new());
  let clip = clipped(vec![(reversed(), vec![raw((1, 2), 0.1, 0.2)])], 0, 8_000);
  assert_eq!(clip.len(), 1, "the segment keeps its text");
  assert_eq!(
    clip[0].tokens_slice(),
    &[TIME + 5, 3, TIME + 10],
    "its timestamps state the raw word's span"
  );
  assert!(
    (clip[0].start() - 0.1).abs() < 1e-6 && (clip[0].end() - 0.2).abs() < 1e-6,
    "retimed to the raw word: {}..{}",
    clip[0].start(),
    clip[0].end()
  );

  let clip = clipped(vec![(reversed(), vec![raw((1, 2), 0.45, 0.55)])], 0, 8_000);
  assert_eq!(clip.len(), 1);
  assert_eq!(
    clip[0].tokens_slice(),
    &[TIME + 22, 3, TIME + 25],
    "the raw word's start, and the clip's end"
  );
  assert!(
    (clip[0].start() - 0.45).abs() < 1e-6 && (clip[0].end() - 0.5).abs() < 1e-6,
    "retimed, then clamped: {}..{}",
    clip[0].start(),
    clip[0].end()
  );

  let unattributed = timed_segment(&[TIME + 20, 3, TIME + 10], 0.4, 0.2, Vec::new());
  assert!(
    clipped(vec![(unattributed, Vec::new())], 0, 8_000).is_empty(),
    "a reversed segment no raw word attributes is dropped"
  );
}

/// LAW (Codex R4, the unattributed lump): **a segment with no raw words
/// keeps only the text a timestamp inside the clip closes, whatever its
/// end says.** None of these wordless lumps runs past the 0.4 s clip:
/// `<|0.00|> a <|0.20|> b <eot>` ends at its last timestamp, 0.20 s, and
/// keeps `a`, for `b` follows the last timestamp inside the clip;
/// `<|0.00|> a b <eot>` ends at the window's end — the clip's own — and
/// nothing closes its text: it is dropped. The timestamps are read in
/// token order, and a timestamp past the clip ends the reading: in
/// `<|0.00|> a <|0.60|> b <|0.20|>` the `<|0.20|>` after a time in the
/// padding closes nothing, and that segment is dropped too.
#[test]
fn an_unattributed_lump_keeps_only_the_text_a_timestamp_inside_the_clip_closes() {
  let eot = SPECIAL;
  let clip_end = crate::audio::whisper::segment::window_span(0, 6_400).1;
  let closed_early = timed_segment(&[TIME, 1, TIME + 10, 2, eot], 0.0, 0.2, Vec::new());
  let unclosed = timed_segment(&[TIME, 1, 2, eot], 0.0, clip_end, Vec::new());
  let after_padding = timed_segment(&[TIME, 1, TIME + 30, 2, TIME + 10], 0.0, 0.2, Vec::new());
  let clip = clipped(
    vec![
      (closed_early, Vec::new()),
      (unclosed, Vec::new()),
      (after_padding, Vec::new()),
    ],
    0,
    6_400,
  );

  assert_eq!(
    clip.len(),
    1,
    "the lumps nothing inside the clip closes are dropped"
  );
  assert_eq!(clip[0].tokens_slice(), &[TIME, 1, TIME + 10, eot]);
  assert_eq!(
    clip[0]
      .token_log_probs_slice()
      .iter()
      .map(|&(token, _)| token)
      .collect::<Vec<_>>(),
    vec![TIME, 1, TIME + 10, eot]
  );
  assert_eq!(clip[0].text(), "<1002>a<1012><1000>");
}

/// LAW (Codex R4, the text past the words): **past its last raw word, a
/// segment keeps only the text a timestamp inside the clip closes.** Inside
/// the 0.4 s clip, with raw words for `a` and `b` only: `<|0.00|> a b c
/// <eot>`, a lump ending at the clip's end, keeps `a b` — no timestamp
/// closes `c`; `<|0.00|> a b c <|0.30|>` keeps `c`, which `<|0.30|>` closes
/// inside the clip.
#[test]
fn past_its_last_word_a_segment_keeps_only_the_text_a_timestamp_inside_closes() {
  let eot = SPECIAL;
  let clip_end = crate::audio::whisper::segment::window_span(0, 6_400).1;
  let words = || vec![word(&[1], 0.0, 0.1), word(&[2], 0.1, 0.2)];
  let raws = || vec![raw((1, 2), 0.0, 0.1), raw((2, 3), 0.1, 0.2)];
  let open_tail = timed_segment(&[TIME, 1, 2, 3, eot], 0.0, clip_end, words());
  let closed_tail = timed_segment(&[TIME, 1, 2, 3, TIME + 15], 0.0, 0.3, words());
  let clip = kept(vec![(open_tail, raws()), (closed_tail, raws())], 0, 6_400);

  assert_eq!(clip.len(), 2);
  assert_eq!(clip[0].0.tokens_slice(), &[TIME, 1, 2, eot]);
  assert_eq!(clip[0].0.text(), "<1002>ab<1000>");
  assert_eq!(spans(&clip[0].1), [(1, 2), (2, 3)], "both raw words kept");
  assert_eq!(clip[1].0.tokens_slice(), &[TIME, 1, 2, 3, TIME + 15]);
  assert_eq!(clip[1].0.text(), "<1002>abc<1017>");
}

/// LAW (Codex R5, [medium]): **a segment with no text is dropped, whether
/// or not anything was removed.** Codex's `<|0.20|> <|0.20|>` inside a
/// 0.4 s clip holds no text: nothing is removed from it, and it is dropped
/// rather than reach the callbacks and the transcript as a phantom; so is
/// `<|0.00|> <|0.20|>`. A segment no raw word attributes whose span is
/// empty is dropped too, though a timestamp inside the clip closes its
/// text: nothing places that text in the clip's audio.
#[test]
fn a_segment_with_no_text_is_dropped_whatever_was_removed() {
  let clip = clipped(
    vec![
      (
        timed_segment(&[TIME + 10, TIME + 10], 0.2, 0.2, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[TIME, TIME + 10], 0.0, 0.2, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[TIME + 10, 1, TIME + 10], 0.2, 0.2, Vec::new()),
        Vec::new(),
      ),
      (
        timed_segment(&[TIME + 10, 2, TIME + 15], 0.2, 0.3, Vec::new()),
        Vec::new(),
      ),
    ],
    0,
    6_400,
  );
  assert_eq!(clip.len(), 1, "only the segment with text and a span stays");
  assert_eq!(clip[0].tokens_slice(), &[TIME + 10, 2, TIME + 15]);
}

/// LAW (Codex R5, restated for R6 row 2): **a raw word belongs to the
/// segment holding its first token, whatever the counts.** Over a window of
/// two segments, `<|0.00|> a ! ! <|0.20|>` and `<|0.20|> c <|0.30|>`, the
/// alignment's text units are owned by where their spans start in the
/// flattened tokens: `a` and both `!` by the first segment, `c` by the
/// second — never by a cursor counting tokens — each span restated in its
/// segment and each frame made the window's samples. A unit straddling the
/// boundary belongs to the segment its first token is in.
#[test]
fn a_raw_word_belongs_to_the_segment_holding_its_first_token() {
  use crate::audio::whisper::segment::own_raw_words;
  let bang = 9u32;
  let first = timed_segment(&[TIME, 1, bang, bang, TIME + 10], 0.0, 0.2, Vec::new());
  let second = timed_segment(&[TIME + 10, 3, TIME + 15], 0.2, 0.3, Vec::new());
  // Spans in the flattened tokens; frames of 20 ms.
  let units = [
    ((1, 2), 0, 5),
    ((2, 3), 5, 6),
    ((3, 4), 6, 7),
    ((6, 7), 10, 15),
    ((3, 7), 7, 13),
  ];
  // Every frame is 320 samples of the window, wherever the window starts.
  let owned = own_raw_words(&[first, second], &units);
  let at = |frame: usize| frame * 320;
  assert_eq!(
    owned[0],
    [
      RawWord::new((1, 2), at(0), at(5)),
      RawWord::new((2, 3), at(5), at(6)),
      RawWord::new((3, 4), at(6), at(7)),
      RawWord::new((3, 7), at(7), at(13)),
    ],
    "the first segment's words, the straddling one among them"
  );
  assert_eq!(
    owned[1],
    [RawWord::new((1, 2), at(10), at(15))],
    "`c` is the second's"
  );
}

/// LAW (Codex R6 row 5, [medium]): **an hour in, a raw word crossing the
/// clip's end is kept.** A 6 088-sample clip an hour into a file: the
/// alignment places `b` from frame 19 — sample 6 080 of the window, eight
/// before the clip's end — to frame 25, past it: a word crossing the end,
/// kept. Read as f32 seconds of the audio, `b` started at 3600.38, sample
/// 6 078.125 of the window, and a relative slack of `2·|t|·ε` — 13.7 samples
/// where the time's own step is 3.9 — put it at the clip's end: the crossing
/// word was cut. The raw words keep the window's own samples, so no time of
/// the audio is compared.
#[test]
fn an_hour_in_a_raw_word_crossing_the_clip_end_is_kept() {
  use crate::audio::whisper::segment::own_raw_words;
  let seek = 57_600_000;
  let (window_start, _) = crate::audio::whisper::segment::window_span(seek, 6_088);
  let segment = timed_segment(
    &[TIME, 1, 2, TIME + 30],
    window_start,
    window_start + 0.6,
    Vec::new(),
  );
  let units = [((1, 2), 0, 19), ((2, 3), 19, 25)];
  let owned = own_raw_words(std::slice::from_ref(&segment), &units);
  let clip = clipped_showing(vec![(segment, owned[0].clone())], seek, 6_088, true);
  assert_eq!(clip.len(), 1, "the segment stays");
  assert_eq!(
    clip[0].text(),
    "ab",
    "the word crossing the clip's end is kept"
  );
}