Skip to content

AI media harness for planning, generating, and editing locally

TypeScript
32.9 KB
Raw Blame
//! Select boundary latents without changing the source archive or runtime ABI.
//! The native setter owns its snapshot, so the temporary archive can be dropped
//! immediately after attachment. End selection uses the original archive.
use super::types::GenerationRequest;
use serde_json::{json, Value};
use std::{
    fs::File,
    io::{Read, Seek, SeekFrom, Write},
};

pub(super) fn validate(request: &GenerationRequest) -> Result<(), String> {
    if let Some(noise) = request.continuation_source_noise {
        if !noise.is_finite() || noise <= 0.0 || noise > 1.0
            || request.continuation_path.is_none() && request.continuation_relative_path.is_none() {
            return Err("Source initialization needs previous latents and a finite noise strength greater than zero and at most one.".into());
        }
    }
    let overlap = request.continuation_overlap_frames.unwrap_or(22);
    if !(22..=362).contains(&overlap) || overlap % 17 != 5 {
        return Err("Continuation overlap must be 22, 39, 56, … frames (at most 362).".into());
    }
    if request
        .continuation_from
        .as_deref()
        .is_some_and(|value| !matches!(value, "start" | "end"))
    {
        return Err("Choose the beginning or end of the source scene.".into());
    }
    if request
        .continuation_source_frames
        .is_some_and(|frames| frames < overlap)
    {
        return Err("The selected scene is shorter than the continuation overlap.".into());
    }
    Ok(())
}

pub(super) fn source_noise(request: &GenerationRequest) -> Option<f32> {
    // Single Shot uses boundary anchors only. Applying the source prior across
    // the entire new interval can freeze/repeat the starting scene. Ignore old
    // queued source-noise values during planning as well as generation.
    if request.single_shot.is_some() { None } else { request.continuation_source_noise }
}

fn integer(meta: &Value, key: &str) -> Result<usize, String> {
    meta[key]
        .as_str()
        .and_then(|value| value.parse().ok())
        .ok_or_else(|| format!("Invalid latent archive {key}."))
}

fn read_rows(
    file: &mut File,
    data_start: u64,
    header: &Value,
    name: &str,
    rows: usize,
    columns: usize,
    start: usize,
    count: usize,
) -> Result<Vec<u8>, String> {
    let tensor = &header[name];
    if tensor["dtype"] != "F32" || tensor["shape"] != json!([rows, columns]) {
        return Err(format!("Invalid {name} latent geometry."));
    }
    let begin = tensor["data_offsets"][0]
        .as_u64()
        .ok_or("Invalid latent offsets.")?;
    let end = tensor["data_offsets"][1]
        .as_u64()
        .ok_or("Invalid latent offsets.")?;
    let row_bytes = columns.checked_mul(4).ok_or("Latent row size overflow.")?;
    let size = rows
        .checked_mul(row_bytes)
        .ok_or("Latent tensor size overflow.")?;
    let file_size = file.metadata().map_err(|e| e.to_string())?.len();
    if end.checked_sub(begin) != Some(size as u64)
        || start.checked_add(count).is_none_or(|n| n > rows)
        || data_start.checked_add(end).is_none_or(|n| n > file_size)
    {
        return Err("Truncated or invalid latent tensor.".into());
    }
    let offset = data_start
        .checked_add(begin)
        .and_then(|n| n.checked_add((start * row_bytes) as u64))
        .ok_or("Latent offset overflow.")?;
    file.seek(SeekFrom::Start(offset))
        .map_err(|e| e.to_string())?;
    let mut bytes = vec![
        0;
        count
            .checked_mul(row_bytes)
            .ok_or("Latent slice size overflow.")?
    ];
    file.read_exact(&mut bytes).map_err(|e| e.to_string())?;
    Ok(bytes)
}

pub(super) fn opening_archive(
    request: &GenerationRequest,
) -> Result<Option<tempfile::TempPath>, String> {
    validate(request)?;
    if request.continuation_from.as_deref() != Some("start") {
        return Ok(None);
    }
    crop_archive(request, false).map(Some)
}

/// Keep the final video latents and both audio channels, without VAE re-encoding.
pub(super) fn tail_archive(path: &std::path::Path, frames: i32) -> Result<tempfile::TempPath, String> {
    let request = GenerationRequest {
        continuation_path: Some(path.to_path_buf()), continuation_overlap_frames: Some(frames),
        ..Default::default()
    };
    validate(&request)?;
    crop_archive(&request, true)
}

fn crop_archive(request: &GenerationRequest, from_end: bool) -> Result<tempfile::TempPath, String> {
    let path = request
        .continuation_path
        .as_ref()
        .ok_or("The continuation source has not been resolved.")?;
    let mut source = File::open(path).map_err(|e| format!("Could not read source latents: {e}"))?;
    let mut length = [0; 8];
    source.read_exact(&mut length).map_err(|e| e.to_string())?;
    let header_len = u64::from_le_bytes(length);
    if header_len > 1024 * 1024 {
        return Err("Invalid latent archive header length.".into());
    }
    let mut bytes = vec![0; header_len as usize];
    source.read_exact(&mut bytes).map_err(|e| e.to_string())?;
    let header: Value = serde_json::from_slice(&bytes).map_err(|e| e.to_string())?;
    let mut meta = header["__metadata__"].clone();
    if meta["slopfab_latents"] != "h3-av-v1" || meta["fps"] != "24" || meta["sampled"] != "1" {
        return Err("Continue requires completed H3 video latents.".into());
    }
    let frames = integer(&meta, "frames")?;
    let width = integer(&meta, "width")?;
    let height = integer(&meta, "height")?;
    if frames < 22
        || frames > i32::MAX as usize
        || frames % 17 != 5
        || width == 0
        || height == 0
        || width > 8192
        || height > 8192
        || width % 32 != 0
        || height % 32 != 0
    {
        return Err("Invalid source latent geometry.".into());
    }
    let overlap = request.continuation_overlap_frames.unwrap_or(22) as usize;
    let scene_frames = request
        .continuation_source_frames
        .map(|n| n as usize)
        .unwrap_or(frames);
    if scene_frames < overlap || scene_frames > frames {
        return Err("Overlap exceeds the selected source scene.".into());
    }
    let latent_frames = |count: usize| (count - 5) / 17 * 5 + 2;
    let video_frames = latent_frames(frames);
    // Continued archives include earlier scenes. New frames add five latent
    // frames per 17 video frames; start at this scene's own latent contribution.
    let first_video = if from_end {
        video_frames - latent_frames(overlap)
    } else if scene_frames == frames {
        0
    } else {
        if scene_frames % 17 != 0 {
            return Err("Invalid continued scene length.".into());
        }
        video_frames
            .checked_sub(scene_frames / 17 * 5)
            .ok_or("Invalid scene latent range.")?
    };
    let row_frames = (width / 32)
        .checked_mul(height / 32)
        .ok_or("Latent canvas overflow.")?;
    let all_video = video_frames
        .checked_mul(row_frames)
        .ok_or("Latent geometry overflow.")?;
    let selected_video = latent_frames(overlap)
        .checked_mul(row_frames)
        .ok_or("Latent geometry overflow.")?;
    let audio_frames = frames
        .checked_mul(5)
        .and_then(|n| n.checked_add(1))
        .ok_or("Latent audio overflow.")?
        / 3;
    let selected_audio = (overlap * 5 + 1) / 3;
    let first_audio = if from_end { audio_frames - selected_audio } else { ((frames - scene_frames) * 5 + 1) / 3 };
    let video = read_rows(
        &mut source,
        header_len + 8,
        &header,
        "video_rows",
        all_video,
        96,
        first_video * row_frames,
        selected_video,
    )?;
    // Audio rows are planar stereo, not interleaved: crop each channel.
    let mut audio = read_rows(
        &mut source,
        header_len + 8,
        &header,
        "audio_rows",
        audio_frames * 2,
        32,
        first_audio,
        selected_audio,
    )?;
    audio.extend(read_rows(
        &mut source,
        header_len + 8,
        &header,
        "audio_rows",
        audio_frames * 2,
        32,
        audio_frames + first_audio,
        selected_audio,
    )?);
    meta["frames"] = json!(overlap.to_string());
    let mut output_header = json!({
        "__metadata__": meta,
        "video_rows": { "dtype": "F32", "shape": [selected_video, 96], "data_offsets": [0, video.len()] },
        "audio_rows": { "dtype": "F32", "shape": [selected_audio * 2, 32], "data_offsets": [video.len(), video.len() + audio.len()] },
    }).to_string();
    while output_header.len() % 8 != 0 {
        output_header.push(' ');
    }
    let mut output = tempfile::NamedTempFile::new().map_err(|e| e.to_string())?;
    output
        .write_all(&(output_header.len() as u64).to_le_bytes())
        .and_then(|_| output.write_all(output_header.as_bytes()))
        .and_then(|_| output.write_all(&video))
        .and_then(|_| output.write_all(&audio))
        .and_then(|_| output.flush())
        .map_err(|e| e.to_string())?;
    // Close the file handle before the DLL opens it (Windows sharing rules).
    Ok(output.into_temp_path())
}

#[cfg(test)]
pub(super) mod tests {
    use super::super::{planning::resolve_plan, references::ReferenceVideos};
    use super::*;
    use std::collections::BTreeMap;

    pub(crate) fn archive(frames: usize) -> tempfile::NamedTempFile {
        let video_rows = ((frames - 5) / 17 * 5 + 2) * 2;
        let audio_rows = ((frames * 5 + 1) / 3) * 2;
        let video_bytes = video_rows * 96 * 4;
        let audio_bytes = audio_rows * 32 * 4;
        let mut header = json!({
            "__metadata__": { "slopfab_latents": "h3-av-v1", "width": "64", "height": "32", "frames": frames.to_string(), "fps": "24", "sampled": "1" },
            "video_rows": { "dtype": "F32", "shape": [video_rows, 96], "data_offsets": [0, video_bytes] },
            "audio_rows": { "dtype": "F32", "shape": [audio_rows, 32], "data_offsets": [video_bytes, video_bytes + audio_bytes] }
        }).to_string();
        while header.len() % 8 != 0 {
            header.push(' ');
        }
        let mut file = tempfile::NamedTempFile::new().unwrap();
        file.write_all(&(header.len() as u64).to_le_bytes())
            .unwrap();
        file.write_all(header.as_bytes()).unwrap();
        for (rows, columns) in [(video_rows, 96), (audio_rows, 32)] {
            for row in 0..rows {
                for _ in 0..columns {
                    file.write_all(&(row as f32).to_le_bytes()).unwrap();
                }
            }
        }
        file.flush().unwrap();
        file
    }

    #[test]
    fn long_shot_plans_full_joined_outputs_and_keeps_source_archives_immutable() {
        use super::super::{types::LatentBridgeRequest, planning::validate_generation_controls};
        let left = archive(124).into_temp_path();
        let right = archive(90).into_temp_path();
        let originals = [std::fs::read(&left).unwrap(), std::fs::read(&right).unwrap()];
        let mut request = GenerationRequest {
            prompt: "The subject continues walking".into(), frames: 30, steps: 4, seed: 1,
            canvas_width: 64, canvas_height: 32,
            bridge_left_path: Some(left.to_path_buf()), bridge_right_path: Some(right.to_path_buf()),
            latent_bridge: Some(LatentBridgeRequest { left_scene_id: "left".into(), right_scene_id: "right".into(),
                left_frames: Some(124), right_frames: Some(90), left_margin_frames: 17, right_margin_frames: 34,
                context_frames: 22, ..Default::default() }), ..Default::default()
        };
        let settings = BTreeMap::from([("slopfab".into(), crate::settings::ProviderSetting {
            enabled: true, model: None, options: BTreeMap::from([("motionCache".into(), crate::settings::ProviderOption::Boolean(true))]),
        })]);
        let plan = resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap();
        assert_eq!(plan.aligned_frames, 260); // 124 + 46 + 90, including replaced margins.
        assert!((plan.duration_seconds - 260.0 / 24.0).abs() < 0.0001);
        for margin in [-17, 1, 357] {
            request.latent_bridge.as_mut().unwrap().left_margin_frames = margin;
            assert!(validate_generation_controls(&request).is_err());
        }
        request.latent_bridge.as_mut().unwrap().left_margin_frames = 0;
        assert!(resolve_plan(&request, &settings, &ReferenceVideos::default()).is_ok());
        request.bridge_right_path = None;
        assert!(validate_generation_controls(&request).is_err());
        assert_eq!(std::fs::read(&left).unwrap(), originals[0]);
        assert_eq!(std::fs::read(&right).unwrap(), originals[1]);
        let wire = serde_json::to_value(request).unwrap();
        assert!(wire.get("bridgeLeftPath").is_none());
        assert_eq!(wire["latentBridge"]["rightMarginFrames"], 34);
    }

    #[test]
    fn single_shot_matches_two_minute_anchored_request() {
        use super::super::{ffi::{Api, RequestHandle}, h3::configure_request, config::Configuration,
            platform::ComputePlatform, planning::RequestPurpose, types::SingleShotRequest};
        use crate::settings::{ProviderOption, ProviderSetting};
        // SlopFab docs/lcs_drift_4way.md and tools/lcs_long_run.py:
        // 73 original frames, 42 x 68 new frames, 25 grid points, delay 4,
        // fixed original anchors, overlap 22, and no regenerated overlap.
        // Small spatial fixtures exercise the bundled DLL without GPU weights.
        let original = archive(73).into_temp_path();
        let original_bytes = std::fs::read(&original).unwrap();
        let settings = BTreeMap::from([("slopfab".into(), ProviderSetting { enabled: true, model: None,
            options: BTreeMap::from([
                ("attention".into(), ProviderOption::String("flash2".into())),
                ("motionCache".into(), ProviderOption::Boolean(true)),
            ]) })]);
        let configuration = Configuration::from_settings(&settings);
        let api = Api::load(&configuration.dll_path).unwrap();
        for index in [0, 1, 41] {
            let source_frames = 73 + index * 68;
            let previous = archive(source_frames).into_temp_path();
            let previous_bytes = std::fs::read(&previous).unwrap();
            let request = GenerationRequest {
                prompt: "The same subject continues moving".into(), frames: 68, steps: 25, seed: 424243 + index as i64,
                canvas_width: 64, canvas_height: 32,
                single_shot: Some(SingleShotRequest { ending_prompt: String::new(), ending_path: None }),
                continuation_path: Some(previous.to_path_buf()), continuation_overlap_frames: Some(22),
                continuation_source_frames: Some(source_frames as i32), continuation_from: Some("end".into()),
                // Single Shot must enforce locking even for a stale false flag.
                continuation_lock_overlap: false, keystone_path: Some(original.to_path_buf()), ..Default::default()
            };
            for platform in [ComputePlatform::Cuda13, ComputePlatform::Vulkan] {
                // Construct the experiment's request independently of Slopus's recipe.
                let experiment = RequestHandle::new(&api).unwrap();
                api.set_prompt(&experiment, &request.prompt).unwrap();
                api.set_frames(&experiment, 68).unwrap();
                // The current C API counts updates; the original used 25 grid points.
                api.set_steps(&experiment, 24).unwrap();
                api.set_seed(&experiment, request.seed as u64).unwrap();
                api.set_resolution(&experiment, 64, 32).unwrap();
                api.set_attention(&experiment, "flash2").unwrap();
                api.set_inference_backend(&experiment, platform.backend()).unwrap();
                api.set_continuation_file(&experiment, &previous, 22).unwrap();
                api.set_continuation_lock_overlap(&experiment, true).unwrap();
                api.set_keystone_file(&experiment, &original, 4).unwrap();
                let expected = api.describe(&experiment).unwrap();
                assert!(expected.contains("90 frames (22 hidden overlap)"));
                assert!(expected.contains("locked video and audio"));
                assert!(expected.contains("capstone locks after 4 video updates"));
                assert!(!expected.contains("overlap replacement"));
                for purpose in [RequestPurpose::Plan, RequestPurpose::Generate] {
                    let actual = RequestHandle::new(&api).unwrap();
                    configure_request(&api, &actual, &request, &configuration, platform, purpose, &ReferenceVideos::default()).unwrap();
                    assert_eq!(api.describe(&actual).unwrap(), expected);
                    let plan = api.resolve(&actual).unwrap();
                    assert_eq!(plan.aligned_frames, source_frames as i32 + 68);
                    assert_eq!(plan.num_model_evaluations, 24);
                }
            }
            assert_eq!(std::fs::read(&previous).unwrap(), previous_bytes);
        }
        assert_eq!(std::fs::read(&original).unwrap(), original_bytes);
    }

    #[test]
    fn single_shot_keystone_adapts_lock_delay_to_short_video_schedules() {
        use super::super::types::SingleShotRequest;
        let source = archive(124).into_temp_path();
        let context = archive(56).into_temp_path();
        let source_bytes = std::fs::read(&source).unwrap();
        let context_bytes = std::fs::read(&context).unwrap();
        let mut request = GenerationRequest { prompt: "Walk forward".into(), frames: 48, steps: 9, seed: 1,
            canvas_width: 64, canvas_height: 32,
            single_shot: Some(SingleShotRequest { ending_prompt: String::new(), ending_path: None }),
            continuation_path: Some(source.to_path_buf()), continuation_overlap_frames: Some(22),
            continuation_from: Some("end".into()), continuation_lock_overlap: true,
            keystone_path: Some(context.to_path_buf()), ..Default::default() };
        let settings = BTreeMap::new();
        let plan = resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap();
        assert_eq!(plan.aligned_frames, 175);
        assert_eq!(plan.model_evaluations, 8);
        assert!(plan.description.contains("one call-only video latent; front restored before output"));
        assert!(plan.description.contains("22 hidden overlap"));
        assert!(!plan.description.contains("overlap replacement"));
        request.continuation_overlap_frames = Some(39);
        assert!(resolve_plan(&request, &settings, &ReferenceVideos::default()).is_err());
        request.continuation_overlap_frames = Some(22);
        request.continuation_source_frames = Some(21);
        assert!(resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap_err().contains("shorter than the continuation overlap"));
        request.continuation_source_frames = Some(22);
        assert!(resolve_plan(&request, &settings, &ReferenceVideos::default()).is_ok());
        request.continuation_source_frames = Some(124);
        assert_eq!(std::fs::read(&source).unwrap(), source_bytes);
        assert_eq!(std::fs::read(&context).unwrap(), context_bytes);
        for steps in [2, 3, 4, 5, 6, 9] {
            request.steps = steps;
            let plan = resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap();
            assert_eq!(plan.aligned_frames, 175);
            assert_eq!(plan.model_evaluations, steps - 1);
            assert!(plan.description.contains(&format!("capstone locks after {} video updates", (steps - 2).min(4))));
        }
        // Audio can add joint evaluations without adding any video updates.
        request.steps = 4;
        request.audio_steps = Some(17);
        let plan = resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap();
        assert!(plan.model_evaluations > 4);
        assert!(plan.description.contains("capstone locks after 2 video updates"));
        request.audio_steps = None;
        request.steps = 9;
        request.continuation_path = None;
        assert!(resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap_err().contains("Previous video"));
    }

    #[test]
    fn single_shot_keystone_keeps_fixed_recipes_in_planning_and_execution() {
        use super::super::{ffi::{Api, RequestHandle}, h3::configure_request, config::Configuration,
            platform::ComputePlatform, planning::RequestPurpose, types::SingleShotRequest};
        use crate::settings::{ProviderOption, ProviderSetting};
        let source = archive(124).into_temp_path();
        let context = archive(56).into_temp_path();
        let request = GenerationRequest { prompt: "Walk forward".into(), frames: 48, steps: 30, seed: 1,
            canvas_width: 64, canvas_height: 32, audio_steps: Some(17),
            single_shot: Some(SingleShotRequest { ending_prompt: String::new(), ending_path: None }),
            continuation_path: Some(source.to_path_buf()), continuation_overlap_frames: Some(22),
            continuation_from: Some("end".into()), continuation_lock_overlap: true,
            keystone_path: Some(context.to_path_buf()), ..Default::default() };
        for (preset, delay, updates) in [("dmad-4step", 3, 4), ("pika-6step", 4, 6)] {
            let settings = BTreeMap::from([("slopfab".into(), ProviderSetting { enabled: true, model: None,
                options: BTreeMap::from([("samplingPreset".into(), ProviderOption::String(preset.into()))]) })]);
            let configuration = Configuration::from_settings(&settings);
            let api = Api::load(&configuration.dll_path).unwrap();
            for platform in [ComputePlatform::Cuda13, ComputePlatform::Vulkan] {
                for purpose in [RequestPurpose::Plan, RequestPurpose::Generate] {
                    let handle = RequestHandle::new(&api).unwrap();
                    configure_request(&api, &handle, &request, &configuration, platform, purpose, &ReferenceVideos::default()).unwrap();
                    let description = api.describe(&handle).unwrap();
                    assert!(description.contains(&format!("capstone locks after {delay} video updates")));
                    assert!(description.contains(&format!("modality updates    video {updates}")));
                    assert!(description.contains("22 hidden overlap"));
                    assert!(!description.contains("overlap replacement"));
                }
            }
        }
    }

    #[test]
    fn single_shot_anchor_plan_matches_preview_with_and_without_a_starting_source() {
        use super::super::{ffi::{Api, RequestHandle}, h3::configure_request, config::Configuration,
            platform::ComputePlatform, planning::{RequestPurpose, validate_generation_controls}, types::SingleShotRequest};
        let source = archive(124).into_temp_path();
        let ending = archive(22).into_temp_path();
        let original = std::fs::read(&source).unwrap();
        let api = Api::load(&crate::slopfab::default_dll_path()).unwrap();
        for continued in [false, true] {
            let mut request = GenerationRequest { prompt: "Walk forward".into(), frames: 48, steps: 4, seed: 1,
                canvas_width: 64, canvas_height: 32,
                single_shot: Some(SingleShotRequest { ending_prompt: "Wave goodbye".into(), ending_path: None }),
                continuation_path: continued.then(|| source.to_path_buf()), continuation_overlap_frames: Some(22),
                continuation_from: Some("end".into()), continuation_lock_overlap: true, ..Default::default() };
            let settings = BTreeMap::new();
            let preview = resolve_plan(&request, &settings, &ReferenceVideos::default()).unwrap();
            request.single_shot.as_mut().unwrap().ending_path = Some(ending.to_path_buf());
            let handle = RequestHandle::new(&api).unwrap();
            configure_request(&api, &handle, &request, &Configuration::from_settings(&settings), ComputePlatform::Cuda13,
                RequestPurpose::Plan, &ReferenceVideos::default()).unwrap();
            let actual = api.resolve(&handle).unwrap();
            assert_eq!(actual.aligned_frames, if continued { 175 } else { 56 });
            assert_eq!(actual.aligned_frames, preview.aligned_frames);
            assert_eq!(preview.model_evaluations, actual.num_model_evaluations * 2);
            assert_eq!(std::fs::read(&source).unwrap(), original);
            let wire = serde_json::to_value(&request).unwrap();
            assert!(wire["singleShot"].get("endingPath").is_none());
            request.frames = 22;
            assert!(validate_generation_controls(&request).unwrap_err().contains("at least 2 seconds"));
        }
    }

    #[test]
    fn single_shot_ignores_old_source_initialization_during_native_planning() {
        use super::super::{ffi::{Api, RequestHandle}, h3::configure_request, config::Configuration,
            platform::ComputePlatform, planning::RequestPurpose, types::SingleShotRequest};
        let source = archive(124).into_temp_path();
        let ending = archive(22).into_temp_path();
        let api = Api::load(&crate::slopfab::default_dll_path()).unwrap();
        api.require_continuation_source_init().unwrap();
        for backend in [ComputePlatform::Cuda13, ComputePlatform::Vulkan] {
            for noise in [0.01, 0.35, 0.7, 1.0] {
                let request = GenerationRequest { prompt: "Keep walking".into(), frames: 119, steps: 8, seed: 1,
                    canvas_width: 64, canvas_height: 32, continuation_path: Some(source.to_path_buf()),
                    continuation_source_noise: Some(noise), single_shot: Some(SingleShotRequest {
                        ending_prompt: "Walk out of view".into(), ending_path: Some(ending.to_path_buf()) }), ..Default::default() };
                validate(&request).unwrap();
                assert_eq!(source_noise(&request), None);
                let handle = RequestHandle::new(&api).unwrap();
                configure_request(&api, &handle, &request, &Configuration::from_settings(&BTreeMap::new()), backend,
                    RequestPurpose::Plan, &ReferenceVideos::default()).unwrap();
                let plan = api.resolve(&handle).unwrap();
                assert!(plan.aligned_frames > 124);
                let mut fresh = request.clone();
                fresh.continuation_source_noise = None;
                let baseline = RequestHandle::new(&api).unwrap();
                configure_request(&api, &baseline, &fresh, &Configuration::from_settings(&BTreeMap::new()), backend,
                    RequestPurpose::Plan, &ReferenceVideos::default()).unwrap();
                let baseline_plan = api.resolve(&baseline).unwrap();
                assert_eq!(plan.aligned_frames, baseline_plan.aligned_frames);
                assert_eq!(plan.num_model_evaluations, baseline_plan.num_model_evaluations);
                // Other native continuation callers may still opt into the API.
                fresh.single_shot = None;
                fresh.continuation_source_noise = Some(noise);
                assert_eq!(source_noise(&fresh), Some(noise));
            }
        }
        for noise in [0.0, -0.1, 1.01, f32::NAN, f32::INFINITY] {
            let request = GenerationRequest { continuation_path: Some(source.to_path_buf()), continuation_source_noise: Some(noise), ..Default::default() };
            assert!(validate(&request).is_err());
            assert!(api.set_continuation_source_init(&RequestHandle::new(&api).unwrap(), noise).is_err());
        }
        assert!(validate(&GenerationRequest { continuation_source_noise: Some(0.7), ..Default::default() }).is_err());
    }

    #[test]
    fn opening_continuation_crops_the_selected_scene_and_both_audio_channels() {
        let source = archive(124);
        let original = std::fs::read(source.path()).unwrap();
        let request = GenerationRequest {
            continuation_path: Some(source.path().into()),
            continuation_from: Some("start".into()),
            continuation_source_frames: Some(85),
            continuation_overlap_frames: Some(22),
            ..Default::default()
        };
        let cropped = opening_archive(&request).unwrap().unwrap();
        let bytes = std::fs::read(&cropped).unwrap();
        let start = u64::from_le_bytes(bytes[..8].try_into().unwrap()) as usize + 8;
        let header: Value = serde_json::from_slice(&bytes[8..start]).unwrap();
        assert_eq!(header["__metadata__"]["frames"], "22");
        assert_eq!(header["video_rows"]["shape"], json!([14, 96]));
        let value = |at: usize| f32::from_le_bytes(bytes[at..at + 4].try_into().unwrap());
        assert_eq!(value(start), 24.0); // First row of the selected scene, not the chain.
        let audio = start + header["audio_rows"]["data_offsets"][0].as_u64().unwrap() as usize;
        assert_eq!(value(audio), 65.0);
        assert_eq!(value(audio + 37 * 32 * 4), 272.0);
        assert_eq!(std::fs::read(source.path()).unwrap(), original);
        let temporary = cropped.to_path_buf();
        drop(cropped);
        assert!(!temporary.exists());
    }

    #[test]
    fn tail_crop_preserves_final_video_rows_and_each_audio_channel() {
        for (frames, first_video, first_audio, right_audio) in [(124, 60.0, 170.0, 377.0), (56, 20.0, 56.0, 149.0)] {
            let source = archive(frames).into_temp_path();
            let original = std::fs::read(&source).unwrap();
            let cropped = tail_archive(&source, 22).unwrap();
            let bytes = std::fs::read(&cropped).unwrap();
            let start = u64::from_le_bytes(bytes[..8].try_into().unwrap()) as usize + 8;
            let header: Value = serde_json::from_slice(&bytes[8..start]).unwrap();
            assert_eq!(header["__metadata__"]["frames"], "22");
            assert_eq!(header["video_rows"]["shape"], json!([14, 96]));
            assert_eq!(header["audio_rows"]["shape"], json!([74, 32]));
            let value = |at: usize| f32::from_le_bytes(bytes[at..at + 4].try_into().unwrap());
            assert_eq!(value(start), first_video);
            assert_eq!(value(start + 13 * 96 * 4), first_video + 13.0);
            let audio = start + header["audio_rows"]["data_offsets"][0].as_u64().unwrap() as usize;
            assert_eq!(value(audio), first_audio);
            assert_eq!(value(audio + 37 * 32 * 4), right_audio);
            assert_eq!(value(audio + 73 * 32 * 4), right_audio + 36.0);
            assert_eq!(std::fs::read(&source).unwrap(), original);
            assert!(tail_archive(&source, frames as i32 + 17).is_err());

            let request = GenerationRequest { prompt: "Continue walking".into(), frames: 22, steps: 4, seed: 1,
                canvas_width: 64, canvas_height: 32, continuation_path: Some(cropped.to_path_buf()),
                continuation_lock_overlap: true, ..Default::default() };
            let plan = resolve_plan(&request, &BTreeMap::new(), &ReferenceVideos::default()).unwrap();
            assert_eq!(plan.aligned_frames, 56); // 22-frame context + 34 newly generated frames.
        }
    }

    #[test]
    fn continuation_plans_custom_overlap_from_either_edge_with_the_bundled_runtime() {
        let source = archive(124).into_temp_path();
        for edge in ["start", "end"] {
            for overlap in [22, 39, 56] {
                let request = GenerationRequest {
                    job_id: "continued".into(),
                    prompt: "Keep moving".into(),
                    frames: 18,
                    steps: 4,
                    seed: 1,
                    canvas_width: 64,
                    canvas_height: 32,
                    continuation_path: Some(source.to_path_buf()),
                    continuation_from: Some(edge.into()),
                    continuation_overlap_frames: Some(overlap),
                    continuation_source_frames: Some(85),
                    ..Default::default()
                };
                let plan =
                    resolve_plan(&request, &BTreeMap::new(), &ReferenceVideos::default()).unwrap();
                let total = if edge == "start" { overlap + 34 } else { 124 + 34 };
                assert_eq!(plan.aligned_frames, total);
                assert!((plan.duration_seconds - total as f64 / 24.0).abs() < 0.0001);
                let wire = serde_json::to_value(&request).unwrap();
                assert_eq!(wire["continuationFrom"], edge);
                assert_eq!(wire["continuationOverlapFrames"], overlap);
                assert_eq!(wire["continuationSourceFrames"], 85);
            }
        }
    }

    #[test]
    fn continuation_rejects_invalid_ranges_and_truncated_archives() {
        for overlap in [0, 21, 23, 379] {
            assert!(validate(&GenerationRequest {
                continuation_overlap_frames: Some(overlap),
                ..Default::default()
            })
            .is_err());
        }
        assert!(validate(&GenerationRequest {
            continuation_source_frames: Some(17),
            ..Default::default()
        })
        .is_err());
        assert!(validate(&GenerationRequest {
            continuation_from: Some("middle".into()),
            ..Default::default()
        })
        .is_err());
        let source = archive(39);
        source.as_file().set_len(1024).unwrap();
        assert!(opening_archive(&GenerationRequest {
            continuation_path: Some(source.path().into()),
            continuation_from: Some("start".into()),
            ..Default::default()
        })
        .is_err());
    }
}