Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

311 KB
Raw Blame
use std::{
    path::{Path, PathBuf},
    sync::Arc,
    time::{Duration, Instant},
};

use cap_enc_ffmpeg::RelocatableSource;
use cap_enc_ffmpeg::fragmented_mp4::{read_fragment_prefix, tail_is_complete};
use cap_enc_ffmpeg::remux::{
    concatenate_audio_to_ogg, concatenate_m4s_segments_with_init,
    concatenate_m4s_segments_with_init_validated, concatenate_video_fragments,
    concatenate_video_fragments_on_timeline, get_media_duration, get_video_base_fps,
    merge_video_audio, probe_media_valid, probe_video_can_decode, probe_video_seek_points,
    remux_file,
};
use cap_project::{
    AudioMeta, Cursors, MultipleSegment, MultipleSegments, ProjectConfiguration, RecordingMeta,
    RecordingMetaInner, StudioRecordingMeta, StudioRecordingStatus, TimelineConfiguration,
    TimelineSegment, VideoMeta,
};
use relative_path::RelativePathBuf;
use tracing::{debug, warn};

use crate::output_pipeline::{HealthSender, PipelineHealthEvent, emit_health};
use crate::studio_recording::CompletedRecording;

mod prefix;
mod preparing_observer;
mod preparing_projection;
mod retirement;

type PreparingRecoveryLock = retirement::RecoveryLease;

pub use preparing_observer::{
    LivePreparingStudioSources, PreparingAudioLease, PreparingAudioTrack, PreparingSidecarKind,
    PreparingSidecarLease, PreparingStudioIdentity, PreparingStudioJob, PreparingStudioObserver,
    PreparingStudioSources, PreparingStudioState, PreparingVideoLease, PreparingVideoTrack,
};
pub use preparing_projection::{
    PreparingAudioInput, PreparingCursorImage, PreparingStudioSegment, PreparingVideoInput,
};

macro_rules! finalization_info {
    ($($arg:tt)*) => {
        tracing::info!(target: "cap_recording::recording_finalization", $($arg)*)
    };
}

#[derive(Debug, Clone)]
pub struct IncompleteRecording {
    pub project_path: PathBuf,
    pub meta: RecordingMeta,
    pub recoverable_segments: Vec<RecoverableSegment>,
    pub estimated_duration: Duration,
}

#[derive(Debug, Clone)]
pub struct RecoverableSegment {
    pub index: u32,
    pub display_fragments: Vec<PathBuf>,
    pub display_init_segment: Option<PathBuf>,
    pub camera_fragments: Option<Vec<PathBuf>>,
    pub camera_init_segment: Option<PathBuf>,
    pub mic_fragments: Option<Vec<PathBuf>>,
    pub system_audio_fragments: Option<Vec<PathBuf>>,
    pub cursor_path: Option<PathBuf>,
}

#[derive(Debug, Clone)]
pub struct RecoveredRecording {
    pub project_path: PathBuf,
    pub meta: StudioRecordingMeta,
}

#[derive(Debug, Clone)]
struct FragmentsInfo {
    fragments: Vec<PathBuf>,
    init_segment: Option<PathBuf>,
}

#[derive(Debug, Clone, Copy)]
enum RecoveryPurpose {
    Recover,
    Finalize,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum VideoValidation {
    Full,
    Bounded,
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum RecoveryCopyDurability {
    Durable,
    Deferred,
}

impl RecoveryPurpose {
    fn video_validation(self, status: Option<StudioRecordingStatus>) -> VideoValidation {
        match (self, status) {
            (Self::Finalize, Some(StudioRecordingStatus::NeedsRemux)) => VideoValidation::Bounded,
            _ => VideoValidation::Full,
        }
    }

    fn success_message(self) -> &'static str {
        match self {
            Self::Recover => "Successfully recovered recording",
            Self::Finalize => "Successfully finalized fragmented recording",
        }
    }

    fn timeline_message(self) -> &'static str {
        match self {
            Self::Recover => "Created project configuration with timeline for recovered recording",
            Self::Finalize => "Created project configuration with timeline for finalized recording",
        }
    }
}

#[derive(Debug, thiserror::Error)]
pub enum RecoveryError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Failed to concatenate video fragments: {0}")]
    VideoConcat(cap_enc_ffmpeg::remux::RemuxError),
    #[error("Failed to concatenate audio fragments: {0}")]
    AudioConcat(cap_enc_ffmpeg::remux::RemuxError),
    #[error("Failed to merge media streams: {0}")]
    MediaMerge(cap_enc_ffmpeg::remux::RemuxError),
    #[error("Failed to serialize meta: {0}")]
    Serialize(#[from] serde_json::Error),
    #[error("No recoverable segments found")]
    NoRecoverableSegments,
    #[error("Meta save failed")]
    MetaSave,
    #[error("Requested recording track failed; partial media preserved: {0}")]
    RequiredTrackFailure(String),
    #[error("Recovery validation failed; original recording preserved: {0}")]
    Validation(String),
    #[error("Recovered video is not playable: {0}")]
    UnplayableVideo(String),
}

pub struct RecoveryManager;

/// Track start times the recorder writes beside an in-progress segment
/// (`crate::studio_recording::SegmentStartTimes`); the in-progress meta has
/// no segments, so this is what recovery aligns the tracks with.
pub const SEGMENT_START_TIMES_FILE: &str = "start-times.json";

fn persisted_start_times(segment_dir: &Path) -> Option<crate::studio_recording::SegmentStartTimes> {
    let raw = std::fs::read(segment_dir.join(SEGMENT_START_TIMES_FILE)).ok()?;
    serde_json::from_slice(&raw)
        .inspect_err(|error| warn!(%error, "Ignoring unreadable segment start times"))
        .ok()
}

const EXPORT_SEEK_PROBE_SAMPLE_COUNT: usize = 8;

impl RecoveryManager {
    fn require_no_track_failure(project_path: &Path) -> Result<(), RecoveryError> {
        if let Ok(meta) = RecordingMeta::load_for_project(project_path)
            && let Some(studio) = meta.studio_meta()
        {
            return studio
                .ensure_ordinary_media_access(project_path)
                .map_err(RecoveryError::RequiredTrackFailure);
        }
        let path = project_path.join("recording-diagnostics.json");
        let raw = match std::fs::read(&path) {
            Ok(raw) => raw,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
            Err(error) => return Err(error.into()),
        };
        let diagnostics: serde_json::Value = serde_json::from_slice(&raw)?;
        let failed = diagnostics
            .get("segments")
            .and_then(serde_json::Value::as_array)
            .is_none_or(|segments| {
                segments.iter().any(|segment| {
                    segment
                        .get("trackFailures")
                        .and_then(serde_json::Value::as_array)
                        .is_none_or(|failures| !failures.is_empty())
                })
            });
        if failed {
            return Err(RecoveryError::RequiredTrackFailure(
                "recording diagnostics retain a required-track failure".into(),
            ));
        }
        Ok(())
    }

    pub fn inspect_recording(project_path: &Path) -> Option<IncompleteRecording> {
        if !project_path.is_dir() {
            return None;
        }

        let _lock = RecoveryLock::acquire(project_path).ok()?;

        if !project_path.join("recording-meta.json").exists() {
            return None;
        }

        let meta = RecordingMeta::load_for_project(project_path).ok()?;

        Self::analyze_incomplete(project_path, &meta)
    }

    pub fn find_incomplete_single(project_path: &Path) -> Option<IncompleteRecording> {
        if !project_path.is_dir() {
            return None;
        }

        let _lock = RecoveryLock::acquire(project_path).ok()?;

        if !project_path.join("recording-meta.json").exists() {
            return None;
        }

        let meta = RecordingMeta::load_for_project(project_path).ok()?;

        if let Some(studio_meta) = meta.studio_meta()
            && Self::should_check_for_recovery(&studio_meta.status())
        {
            Self::analyze_incomplete(project_path, &meta)
        } else {
            None
        }
    }

    pub fn remux_stopped_with_preparing(
        completed: &CompletedRecording,
        mut job: PreparingStudioJob,
    ) -> Result<bool, RecoveryError> {
        let matches = job.claimed().is_some_and(|claim| {
            claim.metadata().project_path == completed.project_path
                && serde_json::to_value(claim.metadata().studio_meta())
                    .ok()
                    .zip(serde_json::to_value(&completed.meta).ok())
                    .is_some_and(|(stopped, supplied)| stopped == supplied)
        });
        if !matches {
            job.unavailable(
                "The completed recording no longer matches its stopped snapshot".into(),
            );
            return Self::remux_if_needed(&completed.project_path);
        }
        Self::remux_with_preparing(&completed.project_path, Some(job))
    }

    pub fn remux_if_needed(project_path: &Path) -> Result<bool, RecoveryError> {
        Self::remux_with_preparing(project_path, None)
    }

    fn remux_with_preparing(
        project_path: &Path,
        preparing: Option<PreparingStudioJob>,
    ) -> Result<bool, RecoveryError> {
        if !project_path.is_dir() {
            return Ok(false);
        }
        let incomplete = {
            let _lock = RecoveryLock::acquire(project_path)?;
            let Ok(meta) = RecordingMeta::load_for_project(project_path) else {
                return Ok(false);
            };
            meta.studio_meta()
                .filter(|studio| Self::should_check_for_recovery(&studio.status()))
                .and_then(|_| Self::analyze_incomplete(project_path, &meta))
        };
        let Some(incomplete) = incomplete else {
            return Ok(false);
        };

        if incomplete.recoverable_segments.is_empty() {
            return Ok(false);
        }

        // Without a preparing editor nothing reads the originals once they are
        // published, so the backup goes with the stop instead of doubling the
        // recording's size on disk for good -- unless it holds a legacy
        // omitted track, which publication leaves out and only the backup
        // keeps.
        let unread = preparing.is_none()
            && legacy_omitted_tracks(&incomplete.meta, project_path)
                .is_ok_and(|tracks| tracks.is_empty());
        let published_workspace = std::cell::RefCell::new(None);
        Self::finalize_with_publication(
            &incomplete,
            RecoveryPurpose::Finalize,
            copy_recovery_input_with_durability,
            |_, _| Ok(()),
            |project, workspace| {
                publish_recovery(project, workspace)?;
                *published_workspace.borrow_mut() = Some(workspace.to_path_buf());
                Ok(())
            },
            RecoveryLock::acquire,
            preparing,
        )?;
        if unread && let Some(workspace) = published_workspace.into_inner() {
            let retired = RecoveryLock::acquire(project_path)
                .and_then(|_lock| retirement::retire_unread_originals(project_path, &workspace));
            if let Err(error) = retired {
                warn!(path = %workspace.display(), %error, "Original media backup retained");
            }
        }
        Ok(true)
    }

    pub fn find_incomplete(recordings_dir: &Path) -> Vec<IncompleteRecording> {
        let mut incomplete = Vec::new();

        let Ok(entries) = std::fs::read_dir(recordings_dir) else {
            return incomplete;
        };

        for entry in entries.flatten() {
            let path = entry.path();
            if !path.is_dir() {
                continue;
            }

            if !path.join("recording-meta.json").exists() {
                continue;
            }

            let Ok(_lock) = RecoveryLock::acquire(&path) else {
                continue;
            };

            let Ok(meta) = RecordingMeta::load_for_project(&path) else {
                continue;
            };

            if let Some(studio_meta) = meta.studio_meta()
                && Self::should_check_for_recovery(&studio_meta.status())
            {
                match Self::analyze_incomplete(&path, &meta) {
                    Some(incomplete_recording) => {
                        incomplete.push(incomplete_recording);
                    }
                    None => {
                        Self::mark_unrecoverable(&path, &meta);
                    }
                }
            }
        }

        incomplete
    }

    fn should_check_for_recovery(status: &StudioRecordingStatus) -> bool {
        match status {
            StudioRecordingStatus::InProgress | StudioRecordingStatus::NeedsRemux => true,
            StudioRecordingStatus::Failed { .. } | StudioRecordingStatus::Complete => false,
        }
    }

    fn analyze_incomplete(
        project_path: &Path,
        meta: &RecordingMeta,
    ) -> Option<IncompleteRecording> {
        let content_dir = project_path.join("content");
        let segments_dir = content_dir.join("segments");

        if !segments_dir.exists() {
            debug!("No segments directory found at {:?}", segments_dir);
            return None;
        }

        let mut recoverable_segments = Vec::new();
        let mut total_duration = Duration::ZERO;

        let mut segment_dirs: Vec<_> = std::fs::read_dir(&segments_dir)
            .ok()?
            .filter_map(|e| e.ok())
            .filter(|e| e.path().is_dir())
            .collect();

        segment_dirs.sort_by_key(|e| {
            let name = e.file_name().to_string_lossy().to_string();
            name.strip_prefix("segment-")
                .and_then(|s| s.parse::<u32>().ok())
                .unwrap_or(u32::MAX)
        });

        for segment_entry in &segment_dirs {
            let segment_path = segment_entry.path();

            let folder_name = segment_entry.file_name().to_string_lossy().to_string();
            let index: u32 = folder_name
                .strip_prefix("segment-")
                .and_then(|s| s.parse().ok())
                .unwrap_or(0);

            let display_info = Self::segment_track_fragments(&segment_path, "display", true);
            let display_fragments = display_info.fragments;
            let display_init_segment = display_info.init_segment;

            if display_fragments.is_empty() {
                debug!(
                    "No display fragments found for segment {} at {:?}",
                    index, segment_path
                );
                continue;
            }

            let camera_info = Self::segment_track_fragments(&segment_path, "camera", false);
            let camera_init_segment = camera_info.init_segment;
            let camera_fragments =
                (!camera_info.fragments.is_empty()).then_some(camera_info.fragments);

            let mic_fragments = Self::find_audio_fragments(&segment_path.join("audio-input"));
            let system_audio_fragments =
                Self::find_audio_fragments(&segment_path.join("system_audio"));

            if let Some(duration) = Self::estimate_fragments_duration(&display_fragments) {
                total_duration += duration;
            }

            let cursor_path = Self::probe_cursor(&segment_path.join("cursor.json"));

            recoverable_segments.push(RecoverableSegment {
                index,
                display_fragments,
                display_init_segment,
                camera_fragments,
                camera_init_segment,
                mic_fragments,
                system_audio_fragments,
                cursor_path,
            });
        }

        if recoverable_segments.is_empty() {
            finalization_info!("No fragmented segments found in {:?}", project_path);
            return None;
        }

        finalization_info!(
            "Found {} fragmented segments in {:?} with estimated duration {:?}",
            recoverable_segments.len(),
            project_path,
            total_duration
        );

        Some(IncompleteRecording {
            project_path: project_path.to_path_buf(),
            meta: meta.clone(),
            recoverable_segments,
            estimated_duration: total_duration,
        })
    }

    fn find_studio_fragments_with_init(dir: &Path) -> FragmentsInfo {
        let mut info = Self::find_complete_fragments_with_init(dir);
        let Some(init) = info.init_segment.clone().or_else(|| {
            let path = dir.join("init.mp4");
            path.is_file().then_some(path)
        }) else {
            return info;
        };
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                let path = entry.path();
                let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
                    continue;
                };
                let Some(final_name) = name.strip_suffix(".tmp") else {
                    continue;
                };
                if Self::m4s_fragment_index(&dir.join(final_name)).is_none()
                    || dir.join(final_name).exists()
                    || !entry.file_type().is_ok_and(|kind| kind.is_file())
                {
                    continue;
                }
                // A malformed or empty tail has nothing to recover. Any other
                // read error keeps the fragment listed: staged finalization
                // refuses to publish a recording with a pending `.tmp`, so
                // the recording stays retryable instead of losing it.
                match read_fragment_prefix(&init, &path) {
                    Ok(_) => info.fragments.push(path),
                    Err(error)
                        if !matches!(
                            error.kind(),
                            std::io::ErrorKind::InvalidData | std::io::ErrorKind::UnexpectedEof
                        ) =>
                    {
                        warn!(path = %path.display(), %error, "Fragment prefix unreadable; keeping it for a retry");
                        info.fragments.push(path);
                    }
                    Err(_) => {}
                }
            }
        }
        info.fragments.sort_by_key(|path| {
            let path = if path.extension().is_some_and(|extension| extension == "tmp") {
                path.with_extension("")
            } else {
                path.clone()
            };
            Self::m4s_fragment_index(&path)
        });
        info.init_segment = Some(init);
        info
    }

    fn find_complete_fragments(dir: &Path) -> Vec<PathBuf> {
        Self::find_complete_fragments_with_init(dir).fragments
    }

    fn find_complete_fragments_with_init(dir: &Path) -> FragmentsInfo {
        use crate::fragmentation::CURRENT_MANIFEST_VERSION;

        let manifest_path = dir.join("manifest.json");
        let mut manifest_init_segment = None;

        if manifest_path.exists()
            && let Ok(content) = std::fs::read_to_string(&manifest_path)
            && let Ok(manifest) = serde_json::from_str::<serde_json::Value>(&content)
        {
            let manifest_version = manifest
                .get("version")
                .and_then(|v| v.as_u64())
                .unwrap_or(1) as u32;

            let manifest_type = manifest
                .get("type")
                .and_then(|t| t.as_str())
                .unwrap_or("fragments");

            let max_supported_version = if manifest_type == "m4s_segments" {
                5
            } else {
                CURRENT_MANIFEST_VERSION
            };

            if manifest_version > max_supported_version {
                warn!(
                    "Manifest version {} is newer than supported {} for type {}",
                    manifest_version, max_supported_version, manifest_type
                );
            }

            let init_segment = manifest
                .get("init_segment")
                .and_then(|i| i.as_str())
                .and_then(|name| recovery_child_path(dir, name))
                .filter(|p| p.exists());
            manifest_init_segment = init_segment.clone();

            let entries = if manifest_type == "m4s_segments" {
                manifest.get("segments").and_then(|s| s.as_array())
            } else {
                manifest.get("fragments").and_then(|f| f.as_array())
            };

            if let Some(entries) = entries {
                let expected_file_size = |f: &serde_json::Value| -> Option<u64> {
                    f.get("file_size").and_then(|s| s.as_u64())
                };

                let mut result: Vec<PathBuf> = entries
                    .iter()
                    .filter(|f| {
                        f.get("is_complete")
                            .and_then(|c| c.as_bool())
                            .unwrap_or(false)
                    })
                    .filter_map(|f| {
                        let path_str = f.get("path").and_then(|p| p.as_str())?;
                        let path = recovery_child_path(dir, path_str)?;
                        if !path.exists() {
                            return None;
                        }

                        if let Some(expected_size) = expected_file_size(f)
                            && let Ok(metadata) = std::fs::metadata(&path)
                            && metadata.len() != expected_size
                        {
                            warn!(
                                "Fragment {} size mismatch: expected {}, got {}",
                                path.display(),
                                expected_size,
                                metadata.len()
                            );
                            return None;
                        }

                        if path
                            .extension()
                            .is_some_and(|extension| extension.eq_ignore_ascii_case("m4s"))
                            && !Self::is_m4s_complete(&path)
                        {
                            warn!("Fragment {} has an incomplete M4S tail", path.display());
                            return None;
                        }

                        if Self::is_video_file(&path) {
                            if init_segment.is_some() {
                                Some(path)
                            } else {
                                match probe_video_can_decode(&path) {
                                    Ok(true) => Some(path),
                                    Ok(false) => {
                                        warn!(
                                            "Fragment {} has no decodable frames",
                                            path.display()
                                        );
                                        None
                                    }
                                    Err(e) => {
                                        warn!(
                                            "Fragment {} validation failed: {}",
                                            path.display(),
                                            e
                                        );
                                        None
                                    }
                                }
                            }
                        } else if probe_media_valid(&path) {
                            Some(path)
                        } else {
                            warn!("Fragment {} is not valid media", path.display());
                            None
                        }
                    })
                    .collect();

                if manifest_type == "m4s_segments" && init_segment.is_some() {
                    let listed: std::collections::HashSet<_> = entries
                        .iter()
                        .filter(|entry| {
                            entry
                                .get("is_complete")
                                .and_then(|complete| complete.as_bool())
                                .unwrap_or(false)
                        })
                        .filter_map(|entry| entry.get("path").and_then(|path| path.as_str()))
                        .filter_map(|path| recovery_child_path(dir, path))
                        .collect();
                    result.extend(Self::probe_m4s_fragments_with_init(dir).into_iter().filter(
                        |path| {
                            !listed.contains(path)
                                && Self::m4s_fragment_index(path).is_some()
                                && path
                                    .symlink_metadata()
                                    .is_ok_and(|metadata| metadata.is_file())
                        },
                    ));
                    result.sort_by(|a, b| {
                        Self::m4s_fragment_index(a)
                            .cmp(&Self::m4s_fragment_index(b))
                            .then_with(|| a.cmp(b))
                    });
                }

                if !result.is_empty() {
                    return FragmentsInfo {
                        fragments: result,
                        init_segment,
                    };
                }
            }
        }

        if let Some(init_segment) = manifest_init_segment.or_else(|| {
            let path = dir.join("init.mp4");
            path.is_file().then_some(path)
        }) {
            let fragments = Self::probe_m4s_fragments_with_init(dir);
            if !fragments.is_empty() {
                return FragmentsInfo {
                    fragments,
                    init_segment: Some(init_segment),
                };
            }
        }

        FragmentsInfo {
            fragments: Self::probe_fragments_in_dir(dir),
            init_segment: None,
        }
    }

    /// One track of a segment directory: its fragments, else the single-file
    /// fallback, else (when `respawn` is set) the first respawned muxer
    /// directory holding fragments. Shared by segment collection and by
    /// recovery validation so neither can disagree about what a segment holds.
    fn segment_track_fragments(segment_path: &Path, track: &str, respawn: bool) -> FragmentsInfo {
        let dir = segment_path.join(track);
        let info = Self::find_studio_fragments_with_init(&dir);
        if !info.fragments.is_empty() {
            return info;
        }

        if let Some(file) = Self::probe_single_file(&segment_path.join(format!("{track}.mp4"))) {
            return FragmentsInfo {
                fragments: vec![file],
                init_segment: None,
            };
        }

        if respawn
            && let Some(info) = Self::respawn_directories(&dir)
                .into_iter()
                .map(|(_, directory)| Self::find_studio_fragments_with_init(&directory))
                .find(|info| !info.fragments.is_empty())
        {
            return info;
        }

        FragmentsInfo {
            fragments: Vec::new(),
            init_segment: None,
        }
    }

    /// Whether a segment directory holds any recoverable media at all.
    ///
    /// A directory with nothing in it is the residue of a resume that failed
    /// before it wrote a frame, and recovery can ignore it. One holding any
    /// track at all is a real inconsistency: skipping it would leave that
    /// footage out of the recovered recording, so it has to be surfaced rather
    /// than waved through.
    fn segment_holds_recoverable_media(segment_path: &Path) -> bool {
        ["display", "camera"].iter().any(|track| {
            !Self::segment_track_fragments(segment_path, track, true)
                .fragments
                .is_empty()
        }) || ["audio-input", "system_audio"]
            .iter()
            .any(|track| Self::find_audio_fragments(&segment_path.join(track)).is_some())
    }

    fn respawn_directories(dir: &Path) -> Vec<(u32, PathBuf)> {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return Vec::new();
        };

        let mut respawn_dirs: Vec<(u32, PathBuf)> = entries
            .filter_map(|e| e.ok())
            .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))
            .filter_map(|e| {
                let name = e.file_name().to_string_lossy().to_string();
                let n: u32 = name.strip_prefix("respawn-")?.parse().ok()?;
                Some((n, e.path()))
            })
            .collect();

        respawn_dirs.sort_by_key(|(n, _)| *n);
        respawn_dirs
    }

    fn collect_respawn_groups(
        dir: &Path,
        health_tx: Option<&HealthSender>,
        recover_complete_prefixes: bool,
    ) -> Vec<(u32, PathBuf, Vec<PathBuf>)> {
        let mut groups = Vec::new();
        for (n, respawn_dir) in Self::respawn_directories(dir) {
            let init_path = respawn_dir.join("init.mp4");
            if !init_path.exists() {
                debug!(
                    "respawn-{} at {} missing init.mp4",
                    n,
                    respawn_dir.display()
                );
                continue;
            }

            Self::rescue_pending_tmp_fragments(&respawn_dir, health_tx, recover_complete_prefixes);

            let Ok(dir_entries) = std::fs::read_dir(&respawn_dir) else {
                debug!(
                    "respawn-{} at {} could not be read",
                    n,
                    respawn_dir.display()
                );
                continue;
            };

            let mut indexed: Vec<(u32, PathBuf)> = dir_entries
                .filter_map(|e| e.ok())
                .map(|e| e.path())
                .filter_map(|p| {
                    let name = p.file_name()?.to_str()?;
                    let idx: u32 = name
                        .strip_prefix("segment_")
                        .and_then(|s| s.strip_suffix(".m4s"))
                        .and_then(|s| s.parse().ok())?;
                    if !Self::is_m4s_complete(&p) {
                        debug!("Skipping incomplete respawn fragment {}", p.display());
                        return None;
                    }
                    Some((idx, p))
                })
                .collect();

            if indexed.is_empty() {
                debug!(
                    "respawn-{} at {} has no segment_*.m4s fragments",
                    n,
                    respawn_dir.display()
                );
                continue;
            }

            indexed.sort_by_key(|(idx, _)| *idx);

            finalization_info!(
                "Including {} fragments from respawn-{} at {}",
                indexed.len(),
                n,
                respawn_dir.display()
            );

            let fragments: Vec<PathBuf> = indexed.into_iter().map(|(_, p)| p).collect();
            groups.push((n, init_path, fragments));
        }

        groups
    }

    fn rescue_pending_tmp_fragments(
        dir: &Path,
        health_tx: Option<&HealthSender>,
        recover_complete_prefixes: bool,
    ) {
        Self::rescue_pending_tmp_fragments_with_copy(
            dir,
            health_tx,
            recover_complete_prefixes,
            Self::copy_recovered_prefix,
        );
    }

    fn rescue_pending_tmp_fragments_with_copy(
        dir: &Path,
        health_tx: Option<&HealthSender>,
        recover_complete_prefixes: bool,
        copy: impl Fn(&Path, &Path, u64) -> std::io::Result<()>,
    ) {
        const MIN_VALID_TMP_SIZE: u64 = 100;

        let Ok(entries) = std::fs::read_dir(dir) else {
            return;
        };

        for entry in entries.flatten() {
            let path = entry.path();
            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
                continue;
            };
            if !name.starts_with("segment_") || !name.ends_with(".m4s.tmp") {
                continue;
            }
            let Ok(metadata) = std::fs::metadata(&path) else {
                continue;
            };
            if metadata.len() < MIN_VALID_TMP_SIZE {
                continue;
            }
            let corrupt_marker = dir.join(format!("{name}.corrupt"));
            if corrupt_marker.exists()
                && (!recover_complete_prefixes
                    || std::fs::read_to_string(&corrupt_marker).ok().as_deref()
                        != Some("truncated_fragment"))
            {
                continue;
            }
            let final_name = name.trim_end_matches(".tmp");
            let final_path = dir.join(final_name);
            if final_path.exists() {
                continue;
            }
            if recover_complete_prefixes && dir.join("init.mp4").is_file() {
                match read_fragment_prefix(&dir.join("init.mp4"), &path) {
                    Ok(prefix) => match copy(&path, &final_path, prefix.length) {
                        Ok(()) => {
                            finalization_info!(
                                "Recovered complete fragment prefix from {}",
                                path.display()
                            );
                        }
                        Err(error) => {
                            warn!(path = %path.display(), %error, "Could not copy recoverable fragment prefix");
                        }
                    },
                    Err(error) => {
                        if error.kind() == std::io::ErrorKind::InvalidData {
                            let _ = std::fs::write(&corrupt_marker, "truncated_fragment");
                        }
                        warn!(path = %path.display(), %error, "Cannot recover fragment prefix");
                        if let Some(health_tx) = health_tx {
                            emit_health(
                                health_tx,
                                PipelineHealthEvent::RecoveryFragmentCorrupt {
                                    path: path.display().to_string(),
                                    reason: error.to_string(),
                                },
                            );
                        }
                    }
                }
                continue;
            }
            match tail_is_complete(&path) {
                Ok(true) => {}
                Ok(false) => {
                    let reason = "truncated_fragment".to_string();
                    warn!("Refusing to rescue truncated fragment {}", path.display());
                    if let Some(health_tx) = health_tx {
                        emit_health(
                            health_tx,
                            PipelineHealthEvent::RecoveryFragmentCorrupt {
                                path: path.display().to_string(),
                                reason: reason.clone(),
                            },
                        );
                    }
                    let _ = std::fs::write(&corrupt_marker, &reason);
                    continue;
                }
                Err(error) => {
                    let reason = error.to_string();
                    warn!(
                        "Failed to inspect in-progress tmp fragment {}: {}",
                        path.display(),
                        error
                    );
                    if let Some(health_tx) = health_tx {
                        emit_health(
                            health_tx,
                            PipelineHealthEvent::RecoveryFragmentCorrupt {
                                path: path.display().to_string(),
                                reason: reason.clone(),
                            },
                        );
                    }
                    let _ = std::fs::write(&corrupt_marker, reason);
                    continue;
                }
            }
            match std::fs::rename(&path, &final_path) {
                Ok(()) => {
                    finalization_info!(
                        "Rescued in-progress tmp fragment: {} -> {} ({} bytes)",
                        path.display(),
                        final_path.display(),
                        metadata.len()
                    );
                }
                Err(e) => {
                    debug!("Failed to rescue tmp fragment {}: {}", path.display(), e);
                }
            }
        }
    }

    fn copy_recovered_prefix(
        source: &Path,
        destination: &Path,
        length: u64,
    ) -> std::io::Result<()> {
        use std::io::Read;

        let nonce = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_err(std::io::Error::other)?
            .as_nanos();
        let temporary =
            destination.with_extension(format!("recovery-{}-{nonce}", std::process::id()));
        let result = (|| {
            let source = std::fs::File::open(source)?;
            let mut output = std::fs::OpenOptions::new()
                .create_new(true)
                .write(true)
                .open(&temporary)?;
            if std::io::copy(&mut source.take(length), &mut output)? != length {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::UnexpectedEof,
                    "Fragment changed during recovery",
                ));
            }
            output.sync_all()?;
            drop(output);
            prefix::publish(&temporary, destination)
        })();
        let _ = std::fs::remove_file(&temporary);
        result
    }

    fn is_video_file(path: &Path) -> bool {
        path.extension()
            .map(|e| e.eq_ignore_ascii_case("mp4") || e.eq_ignore_ascii_case("m4s"))
            .unwrap_or(false)
    }

    fn probe_fragments_in_dir(dir: &Path) -> Vec<PathBuf> {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return Vec::new();
        };

        let mut fragments: Vec<_> = entries
            .filter_map(|e| e.ok())
            .map(|e| e.path())
            .filter(|p| {
                let ext = p
                    .extension()
                    .and_then(|e| e.to_str())
                    .map(|e| e.to_lowercase());
                match ext.as_deref() {
                    Some("m4s") if !Self::is_m4s_complete(p) => false,
                    Some("mp4") | Some("m4s") => match probe_video_can_decode(p) {
                        Ok(true) => true,
                        Ok(false) => {
                            debug!("Skipping {} - no decodable frames", p.display());
                            false
                        }
                        Err(e) => {
                            debug!("Skipping {} - validation failed: {}", p.display(), e);
                            false
                        }
                    },
                    Some("m4a") | Some("ogg") => probe_media_valid(p),
                    _ => false,
                }
            })
            .collect();

        fragments.sort();
        fragments
    }

    fn probe_m4s_fragments_with_init(dir: &Path) -> Vec<PathBuf> {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return Vec::new();
        };

        let mut fragments: Vec<_> = entries
            .filter_map(|e| e.ok())
            .map(|e| e.path())
            .filter(|p| Self::is_m4s_complete(p))
            .collect();

        fragments.sort_by(|a, b| {
            Self::m4s_fragment_index(a)
                .cmp(&Self::m4s_fragment_index(b))
                .then_with(|| a.cmp(b))
        });
        fragments
    }

    pub fn is_m4s_complete(path: &Path) -> bool {
        const MIN_VALID_FRAGMENT_SIZE: u64 = 100;

        path.extension()
            .is_some_and(|extension| extension.eq_ignore_ascii_case("m4s"))
            && std::fs::symlink_metadata(path).is_ok_and(|metadata| {
                metadata.is_file() && metadata.len() >= MIN_VALID_FRAGMENT_SIZE
            })
            && tail_is_complete(path).unwrap_or(false)
    }

    fn m4s_fragment_index(path: &Path) -> Option<u64> {
        path.file_name()?
            .to_str()?
            .strip_prefix("segment_")?
            .strip_suffix(".m4s")?
            .parse()
            .ok()
    }

    fn probe_single_file(path: &Path) -> Option<PathBuf> {
        if !path.exists() {
            return None;
        }

        if Self::is_video_file(path) {
            match probe_video_can_decode(path) {
                Ok(true) => Some(path.to_path_buf()),
                Ok(false) => {
                    debug!("Single file {} has no decodable frames", path.display());
                    None
                }
                Err(e) => {
                    debug!("Single file {} validation failed: {}", path.display(), e);
                    None
                }
            }
        } else if probe_media_valid(path) {
            Some(path.to_path_buf())
        } else {
            None
        }
    }

    fn find_audio_fragments(base_path: &Path) -> Option<Vec<PathBuf>> {
        let dir_fragments = Self::find_complete_fragments(base_path);
        if !dir_fragments.is_empty() {
            return Some(dir_fragments);
        }

        let ogg_path = base_path.with_extension("ogg");
        if let Some(p) = Self::probe_single_file(&ogg_path) {
            return Some(vec![p]);
        }

        let m4a_path = base_path.with_extension("m4a");
        if let Some(p) = Self::probe_single_file(&m4a_path) {
            return Some(vec![p]);
        }

        let mp3_path = base_path.with_extension("mp3");
        Self::probe_single_file(&mp3_path).map(|p| vec![p])
    }

    fn probe_cursor(path: &Path) -> Option<PathBuf> {
        if path.exists() {
            Some(path.to_path_buf())
        } else {
            None
        }
    }

    fn estimate_fragments_duration(fragments: &[PathBuf]) -> Option<Duration> {
        let mut total = Duration::ZERO;

        for fragment in fragments {
            let prefix_duration = fragment
                .extension()
                .is_some_and(|extension| extension == "tmp")
                .then(|| {
                    read_fragment_prefix(&fragment.with_file_name("init.mp4"), fragment)
                        .ok()
                        .map(|prefix| prefix.duration)
                })
                .flatten();
            if let Some(duration) = prefix_duration.or_else(|| get_media_duration(fragment)) {
                total += duration;
            }
        }

        if total.is_zero() { None } else { Some(total) }
    }

    /// Reads the display media duration the recorder persisted into the
    /// project's default timeline, used to cross-check the remuxed container.
    fn expected_display_duration_from_config(
        project_path: &Path,
        segment_index: u32,
    ) -> Option<std::time::Duration> {
        let config = std::fs::read_to_string(project_path.join("project-config.json")).ok()?;
        let value: serde_json::Value = serde_json::from_str(&config).ok()?;
        let segments = value.get("timeline")?.get("segments")?.as_array()?;
        let segment = segments.iter().find(|s| {
            s.get("recordingSegment")
                .and_then(serde_json::Value::as_u64)
                == Some(u64::from(segment_index))
        })?;
        let end = segment.get("end")?.as_f64()?;
        let start = segment
            .get("start")
            .and_then(serde_json::Value::as_f64)
            .unwrap_or(0.0);
        (end > start && end.is_finite()).then(|| std::time::Duration::from_secs_f64(end - start))
    }

    pub fn recover(recording: &IncompleteRecording) -> Result<RecoveredRecording, RecoveryError> {
        Self::finalize_with_purpose(recording, RecoveryPurpose::Recover)
    }

    pub fn finalize(recording: &IncompleteRecording) -> Result<RecoveredRecording, RecoveryError> {
        Self::finalize_with_purpose(recording, RecoveryPurpose::Finalize)
    }

    pub fn finalize_with_preparing(
        recording: &IncompleteRecording,
        job: PreparingStudioJob,
    ) -> Result<RecoveredRecording, RecoveryError> {
        Self::finalize_with_publication(
            recording,
            RecoveryPurpose::Finalize,
            copy_recovery_input_with_durability,
            |_, _| Ok(()),
            publish_recovery,
            RecoveryLock::acquire,
            Some(job),
        )
    }

    pub fn finalize_with_relocatable_source(
        recording: &IncompleteRecording,
        source: &RelocatableSource,
    ) -> Result<RecoveredRecording, RecoveryError> {
        Self::finalize_with_publication(
            recording,
            RecoveryPurpose::Finalize,
            copy_recovery_input_with_durability,
            |_, _| Ok(()),
            |project, workspace| publish_recovery_with_source(project, workspace, source),
            RecoveryLock::acquire_for_preparing_preview,
            None,
        )
    }

    fn finalize_with_purpose(
        recording: &IncompleteRecording,
        purpose: RecoveryPurpose,
    ) -> Result<RecoveredRecording, RecoveryError> {
        Self::finalize_with_operations(
            recording,
            purpose,
            copy_recovery_input_with_durability,
            |_, _| Ok(()),
        )
    }

    fn finalize_with_operations(
        recording: &IncompleteRecording,
        purpose: RecoveryPurpose,
        copy_input: impl FnMut(&Path, &Path, RecoveryCopyDurability) -> Result<(), RecoveryError>,
        before_source_check: impl FnOnce(&Path, &Path) -> Result<(), RecoveryError>,
    ) -> Result<RecoveredRecording, RecoveryError> {
        Self::finalize_with_publication(
            recording,
            purpose,
            copy_input,
            before_source_check,
            publish_recovery,
            RecoveryLock::acquire,
            None,
        )
    }

    fn finalize_with_publication(
        recording: &IncompleteRecording,
        purpose: RecoveryPurpose,
        mut copy_input: impl FnMut(&Path, &Path, RecoveryCopyDurability) -> Result<(), RecoveryError>,
        before_source_check: impl FnOnce(&Path, &Path) -> Result<(), RecoveryError>,
        publish: impl FnOnce(&Path, &Path) -> Result<(), RecoveryError>,
        acquire: impl FnOnce(&Path) -> Result<RecoveryLock, RecoveryError>,
        preparing: Option<PreparingStudioJob>,
    ) -> Result<RecoveredRecording, RecoveryError> {
        let started = Instant::now();
        Self::require_no_track_failure(&recording.project_path)?;
        let project = &recording.project_path;
        let lock = HeldRecoveryLock::new(acquire(project)?, preparing.is_some());
        let mut preparing = preparing;
        let before = recovery_snapshot(project)?;
        debug!(
            elapsed_ms = started.elapsed().as_secs_f64() * 1000.0,
            "Studio finalization source snapshot ready"
        );
        let current = RecordingMeta::load_for_project(project)
            .map_err(|error| RecoveryError::Validation(error.to_string()))?;
        if serde_json::to_value(&current)? != serde_json::to_value(&recording.meta)? {
            return Err(RecoveryError::Validation(
                "Recording metadata changed".into(),
            ));
        }
        let video_validation =
            purpose.video_validation(current.studio_meta().map(|studio| studio.status()));
        let staging_durability = match video_validation {
            VideoValidation::Full => RecoveryCopyDurability::Durable,
            VideoValidation::Bounded => RecoveryCopyDurability::Deferred,
        };
        Self::require_recoverable_tracks(recording)?;
        let preparing_source = prepare_studio_source(recording, preparing.as_mut(), &lock);
        let workspace = project.join(format!(".recovery-{}", uuid::Uuid::new_v4()));
        create_private_recovery_dir(&workspace)?;
        let staged = workspace.join("staged");
        create_private_recovery_dir(&staged)?;
        let prepared = (|| {
            let copying = Instant::now();
            for name in RECOVERY_INPUTS {
                let source = project.join(name);
                if source.try_exists()? {
                    copy_input(&source, &staged.join(name), staging_durability)?;
                }
            }
            debug!(
                elapsed_ms = copying.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization staging copy ready"
            );
            let checking = Instant::now();
            // Clean finalization mutates only staged bytes and rechecks originals before publication.
            if recovery_snapshot(&staged)? != before
                || (video_validation == VideoValidation::Full
                    && recovery_snapshot(project)? != before)
            {
                return Err(RecoveryError::Validation(
                    "Recording changed while copying".into(),
                ));
            }
            debug!(
                elapsed_ms = checking.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization staging snapshot ready"
            );
            let staged_meta = RecordingMeta::load_for_project(&staged)
                .map_err(|error| RecoveryError::Validation(error.to_string()))?;
            for (index, track) in legacy_omitted_tracks(&staged_meta, &staged)? {
                let segment = staged.join(format!("content/segments/segment-{index}"));
                for suffix in ["", ".mp4", ".m4a", ".ogg", ".mp3"] {
                    let path = segment.join(format!("{track}{suffix}"));
                    let metadata = match path.symlink_metadata() {
                        Ok(metadata) => metadata,
                        Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
                        Err(error) => return Err(error.into()),
                    };
                    reject_recovery_link(&metadata)?;
                    if metadata.is_dir() {
                        std::fs::remove_dir_all(&path)?;
                    } else {
                        std::fs::remove_file(&path)?;
                    }
                }
            }
            validate_recovery_manifests(&staged.join("content"))?;
            let segments = staged.join("content/segments");
            for entry in std::fs::read_dir(segments)? {
                let entry = entry?;
                if entry.file_type()?.is_dir() {
                    for track in ["display", "camera"] {
                        let directory = entry.path().join(track);
                        Self::rescue_pending_tmp_fragments(&directory, None, true);
                        for (_, respawn) in Self::respawn_directories(&directory) {
                            Self::rescue_pending_tmp_fragments(&respawn, None, true);
                        }
                    }
                }
            }
            let analyzing = Instant::now();
            let staged_recording = Self::analyze_incomplete(&staged, &staged_meta)
                .ok_or(RecoveryError::NoRecoverableSegments)?;
            if staged_recording.recoverable_segments.iter().any(|segment| {
                segment
                    .display_fragments
                    .iter()
                    .chain(segment.camera_fragments.iter().flatten())
                    .any(|path| path.extension().is_some_and(|extension| extension == "tmp"))
            }) {
                return Err(RecoveryError::Validation(
                    "Failed to stage a complete fragment prefix".into(),
                ));
            }
            debug!(
                elapsed_ms = analyzing.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization staged analysis ready"
            );
            Self::require_recoverable_tracks(&staged_recording)?;
            Self::require_local_fragments(&staged_recording)?;
            let validating = Instant::now();
            Self::validate_staged_inputs(&staged_recording, video_validation)?;
            debug!(
                elapsed_ms = validating.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization staged inputs validated"
            );
            let remuxing = Instant::now();
            let recovered = Self::finalize_staged(&staged_recording, purpose, video_validation)?;
            debug!(
                elapsed_ms = remuxing.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization media ready"
            );
            let config = ProjectConfiguration::load(&staged)?;
            config
                .validate()
                .map_err(|error| RecoveryError::Validation(error.to_string()))?;
            let persisted = RecordingMeta::load_for_project(&staged)
                .map_err(|error| RecoveryError::Validation(error.to_string()))?;
            if serde_json::to_value(persisted.studio_meta())?
                != serde_json::to_value(&recovered.meta)?
            {
                return Err(RecoveryError::Validation("Staged metadata mismatch".into()));
            }
            let syncing = Instant::now();
            sync_recovery_input(&staged)?;
            debug!(
                elapsed_ms = syncing.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization staging synced"
            );
            before_source_check(project, &staged)?;
            Self::require_no_track_failure(project)?;
            let rechecking = Instant::now();
            if recovery_snapshot(project)? != before {
                return Err(RecoveryError::Validation(
                    "Recording changed before publication".into(),
                ));
            }
            debug!(
                elapsed_ms = rechecking.elapsed().as_secs_f64() * 1000.0,
                "Studio finalization source rechecked"
            );
            Ok(recovered.meta)
        })();
        let meta = match prepared {
            Ok(meta) => meta,
            Err(error) => {
                let _ = std::fs::remove_dir_all(&workspace);
                return Err(error);
            }
        };
        if let Some(source) = &preparing_source {
            publish_recovery_with_source(project, &workspace, source)?;
            if let Some(job) = &mut preparing {
                job.mark_publication_succeeded();
            }
        } else {
            publish(project, &workspace)?;
        }
        debug!(
            elapsed_ms = started.elapsed().as_secs_f64() * 1000.0,
            "Studio finalization complete"
        );
        if matches!(purpose, RecoveryPurpose::Finalize)
            && preparing_source.is_some()
            && let HeldRecoveryLock::Shared(lease) = &lock
            && let Err(error) = lease.retire_originals(project, &workspace)
        {
            warn!(path = %workspace.display(), %error, "Original media backup retained");
        }
        Ok(RecoveredRecording {
            project_path: project.clone(),
            meta,
        })
    }

    fn validate_staged_inputs(
        recording: &IncompleteRecording,
        video_validation: VideoValidation,
    ) -> Result<(), RecoveryError> {
        for segment in &recording.recoverable_segments {
            if video_validation == VideoValidation::Full || segment.display_init_segment.is_none() {
                validate_recovery_video_inputs(
                    &segment.display_fragments,
                    segment.display_init_segment.as_deref(),
                    &recording.project_path,
                    video_validation,
                )?;
            }
            let display_dir = recording.project_path.join(format!(
                "content/segments/segment-{}/display",
                segment.index
            ));
            if video_validation == VideoValidation::Full || segment.display_init_segment.is_none() {
                for (_, init, fragments) in Self::collect_respawn_groups(&display_dir, None, true) {
                    validate_recovery_video_inputs(
                        &fragments,
                        Some(&init),
                        &recording.project_path,
                        video_validation,
                    )?;
                }
            }
            if let Some(fragments) = &segment.camera_fragments
                && (video_validation == VideoValidation::Full
                    || segment.camera_init_segment.is_none())
            {
                validate_recovery_video_inputs(
                    fragments,
                    segment.camera_init_segment.as_deref(),
                    &recording.project_path,
                    video_validation,
                )?;
            }
            let audio = segment
                .mic_fragments
                .iter()
                .flatten()
                .chain(segment.system_audio_fragments.iter().flatten())
                .collect::<Vec<_>>();
            validate_recovered_audio_in_order(&audio)?;
        }
        Ok(())
    }

    fn require_local_fragments(recording: &IncompleteRecording) -> Result<(), RecoveryError> {
        let content = recording.project_path.join("content").canonicalize()?;
        for segment in &recording.recoverable_segments {
            for path in segment
                .display_fragments
                .iter()
                .chain(segment.display_init_segment.iter())
                .chain(segment.camera_fragments.iter().flatten())
                .chain(segment.camera_init_segment.iter())
                .chain(segment.mic_fragments.iter().flatten())
                .chain(segment.system_audio_fragments.iter().flatten())
            {
                if !path.canonicalize()?.starts_with(&content) {
                    return Err(RecoveryError::Validation(
                        "Fragment escapes recording content".into(),
                    ));
                }
            }
        }
        Ok(())
    }

    fn require_recoverable_tracks(recording: &IncompleteRecording) -> Result<(), RecoveryError> {
        let Some(StudioRecordingMeta::MultipleSegments { inner }) = recording.meta.studio_meta()
        else {
            return Err(RecoveryError::Validation(
                "Recovery requires segmented Studio metadata".into(),
            ));
        };
        let legacy_omitted = legacy_omitted_tracks(&recording.meta, &recording.project_path)?;
        let mut indexes = std::collections::BTreeSet::new();
        for segment in &recording.recoverable_segments {
            if !indexes.insert(segment.index) || segment.display_fragments.is_empty() {
                return Err(RecoveryError::Validation(
                    "Missing or duplicate display segment".into(),
                ));
            }
            let original = inner.segments.get(segment.index as usize);
            let dir = recording
                .project_path
                .join(format!("content/segments/segment-{}", segment.index));
            for (name, known, fragments) in [
                (
                    "camera",
                    original.is_some_and(|s| s.camera.is_some()),
                    segment.camera_fragments.as_ref(),
                ),
                (
                    "audio-input",
                    original.is_some_and(|s| s.mic.is_some()),
                    segment.mic_fragments.as_ref(),
                ),
                (
                    "system_audio",
                    original.is_some_and(|s| s.system_audio.is_some()),
                    segment.system_audio_fragments.as_ref(),
                ),
            ] {
                let present = ["", ".mp4", ".m4a", ".ogg", ".mp3"]
                    .iter()
                    .any(|suffix| dir.join(format!("{name}{suffix}")).exists());
                let legacy_discarded = legacy_omitted.contains(&(segment.index as usize, name));
                if (known || (present && !legacy_discarded)) && fragments.is_none_or(Vec::is_empty)
                {
                    return Err(RecoveryError::Validation(format!(
                        "Missing or invalid {name} in segment {}",
                        segment.index
                    )));
                }
            }
        }
        for index in 0..inner.segments.len() {
            if !indexes.contains(&(index as u32)) {
                return Err(RecoveryError::Validation(format!(
                    "Missing display segment {index}"
                )));
            }
        }
        for entry in std::fs::read_dir(recording.project_path.join("content/segments"))? {
            let entry = entry?;
            let Some(index) = entry
                .file_name()
                .to_str()
                .and_then(|name| name.strip_prefix("segment-"))
                .and_then(|value| value.parse::<u32>().ok())
            else {
                continue;
            };

            if indexes.contains(&index) {
                continue;
            }

            // An interrupted resume, a crash or a power loss can leave a segment
            // directory behind that holds no media at all. It contributes
            // nothing to the recording, so ignoring it is what lets the segments
            // that do hold footage be recovered. A directory holding any
            // recoverable track is not that, and stays fatal: recovering around
            // it would silently drop that footage from the recording.
            if !Self::segment_holds_recoverable_media(&entry.path()) {
                warn!(
                    segment = index,
                    path = %entry.path().display(),
                    "Ignoring segment directory without recoverable media"
                );
                continue;
            }

            return Err(RecoveryError::Validation(format!(
                "Unrecoverable display segment {index}"
            )));
        }
        Ok(())
    }

    fn finalize_segment_video(
        recording: &IncompleteRecording,
        segment: &RecoverableSegment,
        segment_dir: &Path,
        video_validation: VideoValidation,
    ) -> Result<(), RecoveryError> {
        let video_started = Instant::now();
        let display_output = segment_dir.join("display.mp4");
        let display_dir = segment_dir.join("display");

        if segment.display_fragments.len() == 1 && segment.display_init_segment.is_none() {
            let source = &segment.display_fragments[0];
            if source != &display_output {
                finalization_info!("Moving single display fragment to {:?}", display_output);
                std::fs::rename(source, &display_output)?;
            }
            Self::validate_required_video(&display_output, "display", video_validation)?;
            if display_dir.exists()
                && let Err(e) = std::fs::remove_dir_all(&display_dir)
            {
                debug!("Failed to clean up display dir {:?}: {e}", display_dir);
            }
        } else if !segment.display_fragments.is_empty() {
            let finalize_result = if display_dir.exists() {
                Self::finalize_to_progressive_mp4_with_validation(
                    &display_dir,
                    &display_output,
                    None,
                    video_validation,
                    true,
                )
                .map(|_| ())
            } else {
                Self::finalize_fragments_to_progressive_mp4(
                    &segment.display_fragments,
                    segment.display_init_segment.as_deref(),
                    &display_output,
                    "display",
                    video_validation,
                )
            };

            match finalize_result {
                Ok(()) => {}
                Err(err) => {
                    if let Err(e) = std::fs::remove_file(&display_output)
                        && e.kind() != std::io::ErrorKind::NotFound
                    {
                        debug!(
                            "Failed to remove invalid display output {:?}: {e}",
                            display_output
                        );
                    }
                    return Err(err);
                }
            }

            if display_dir.exists()
                && let Err(e) = std::fs::remove_dir_all(&display_dir)
            {
                debug!("Failed to clean up display dir {:?}: {e}", display_dir);
            }
        }

        // Sync invariant: the remuxed display track must match the media
        // span the recorder persisted from its capture timestamps.
        if display_output.is_file()
            && let Some(expected) =
                Self::expected_display_duration_from_config(&recording.project_path, segment.index)
        {
            crate::output_validation::check_display_sync_span(&display_output, expected);
        }

        if let Some(camera_frags) = &segment.camera_fragments {
            let camera_output = segment_dir.join("camera.mp4");
            if camera_frags.len() == 1 && segment.camera_init_segment.is_none() {
                if camera_frags[0] != camera_output {
                    std::fs::rename(&camera_frags[0], &camera_output)?;
                }
                Self::validate_required_video(&camera_output, "camera", video_validation)?;
            } else {
                Self::finalize_fragments_to_progressive_mp4(
                    camera_frags,
                    segment.camera_init_segment.as_deref(),
                    &camera_output,
                    "camera",
                    video_validation,
                )?;
            }
            let camera_dir = segment_dir.join("camera");
            if camera_dir.exists() {
                std::fs::remove_dir_all(camera_dir)?;
            }
        }

        debug!(
            segment = segment.index,
            elapsed_ms = video_started.elapsed().as_secs_f64() * 1000.0,
            "Studio finalization segment video ready"
        );
        Ok(())
    }

    fn finalize_segment_audio(
        segment: &RecoverableSegment,
        segment_dir: &Path,
    ) -> Result<(), RecoveryError> {
        let audio_started = Instant::now();

        if let Some(mic_frags) = &segment.mic_fragments {
            let mic_output =
                segment_dir.join(finalized_audio_name(segment_dir, "audio-input", mic_frags));
            if mic_frags.len() == 1 {
                let source = &mic_frags[0];
                let is_ogg = source.extension().map(|e| e == "ogg").unwrap_or(false);
                if mic_output
                    .extension()
                    .is_some_and(|extension| extension == "m4a")
                {
                    finalize_m4a(source, &mic_output)?;
                } else if source != &mic_output {
                    if is_ogg {
                        finalization_info!("Moving single mic fragment to {:?}", mic_output);
                        std::fs::rename(source, &mic_output)?;
                    } else {
                        finalization_info!("Transcoding single mic fragment to {:?}", mic_output);
                        concatenate_audio_to_ogg(mic_frags, &mic_output)
                            .map_err(RecoveryError::AudioConcat)?;
                        if let Err(e) = std::fs::remove_file(source) {
                            debug!("Failed to remove mic source {:?}: {e}", source);
                        }
                    }
                    let mic_dir = segment_dir.join("audio-input");
                    if mic_dir.exists()
                        && let Err(e) = std::fs::remove_dir_all(&mic_dir)
                    {
                        debug!("Failed to clean up mic dir {:?}: {e}", mic_dir);
                    }
                }
            } else if mic_frags.len() > 1 {
                finalization_info!(
                    "Concatenating {} mic fragments to {:?}",
                    mic_frags.len(),
                    mic_output
                );
                concatenate_audio_to_ogg(mic_frags, &mic_output)
                    .map_err(RecoveryError::AudioConcat)?;

                for fragment in mic_frags {
                    if let Err(e) = std::fs::remove_file(fragment) {
                        debug!("Failed to remove mic fragment {:?}: {e}", fragment);
                    }
                }
                let mic_dir = segment_dir.join("audio-input");
                if mic_dir.exists()
                    && let Err(e) = std::fs::remove_dir_all(&mic_dir)
                {
                    debug!("Failed to clean up mic dir {:?}: {e}", mic_dir);
                }
            }
        }

        if let Some(system_frags) = &segment.system_audio_fragments {
            let system_output = segment_dir.join(finalized_audio_name(
                segment_dir,
                "system_audio",
                system_frags,
            ));
            if system_frags.len() == 1 {
                let source = &system_frags[0];
                let is_ogg = source.extension().map(|e| e == "ogg").unwrap_or(false);
                if system_output
                    .extension()
                    .is_some_and(|extension| extension == "m4a")
                {
                    finalize_m4a(source, &system_output)?;
                } else if source != &system_output {
                    if is_ogg {
                        finalization_info!(
                            "Moving single system audio fragment to {:?}",
                            system_output
                        );
                        std::fs::rename(source, &system_output)?;
                    } else {
                        finalization_info!(
                            "Transcoding single system audio fragment to {:?}",
                            system_output
                        );
                        concatenate_audio_to_ogg(system_frags, &system_output)
                            .map_err(RecoveryError::AudioConcat)?;
                        if let Err(e) = std::fs::remove_file(source) {
                            debug!("Failed to remove system audio source {:?}: {e}", source);
                        }
                    }
                    let system_dir = segment_dir.join("system_audio");
                    if system_dir.exists()
                        && let Err(e) = std::fs::remove_dir_all(&system_dir)
                    {
                        debug!("Failed to clean up system audio dir {:?}: {e}", system_dir);
                    }
                }
            } else if system_frags.len() > 1 {
                finalization_info!(
                    "Concatenating {} system audio fragments to {:?}",
                    system_frags.len(),
                    system_output
                );
                concatenate_audio_to_ogg(system_frags, &system_output)
                    .map_err(RecoveryError::AudioConcat)?;

                for fragment in system_frags {
                    if let Err(e) = std::fs::remove_file(fragment) {
                        debug!("Failed to remove system audio fragment {:?}: {e}", fragment);
                    }
                }
                let system_dir = segment_dir.join("system_audio");
                if system_dir.exists()
                    && let Err(e) = std::fs::remove_dir_all(&system_dir)
                {
                    debug!("Failed to clean up system audio dir {:?}: {e}", system_dir);
                }
            }
        }
        debug!(
            segment = segment.index,
            elapsed_ms = audio_started.elapsed().as_secs_f64() * 1000.0,
            "Studio finalization segment audio remuxed"
        );
        Ok(())
    }

    fn validate_segment_audio(
        segment: &RecoverableSegment,
        segment_dir: &Path,
        video_validation: VideoValidation,
    ) -> [Option<Result<(), RecoveryError>>; 2] {
        [
            ("audio-input", segment.mic_fragments.as_deref()),
            ("system_audio", segment.system_audio_fragments.as_deref()),
        ]
        .map(|(stem, fragments)| {
            fragments.map(|fragments| {
                validate_recovery_track(
                    &segment_dir.join(finalized_audio_name(segment_dir, stem, fragments)),
                    ffmpeg::media::Type::Audio,
                    video_validation,
                )
            })
        })
    }

    fn finalize_staged(
        recording: &IncompleteRecording,
        purpose: RecoveryPurpose,
        video_validation: VideoValidation,
    ) -> Result<RecoveredRecording, RecoveryError> {
        Self::require_no_track_failure(&recording.project_path)?;
        if recording.recoverable_segments.is_empty() {
            return Err(RecoveryError::NoRecoverableSegments);
        }

        let mut audio_validations = Vec::with_capacity(recording.recoverable_segments.len());
        for segment in &recording.recoverable_segments {
            let segment_dir = recording
                .project_path
                .join("content/segments")
                .join(format!("segment-{}", segment.index));

            let (video, audio) = std::thread::scope(|scope| {
                let audio = std::thread::Builder::new()
                    .name("studio-audio-finalize".into())
                    .stack_size(AUDIO_FINALIZE_STACK_SIZE)
                    .spawn_scoped(scope, || {
                        Self::finalize_segment_audio(segment, &segment_dir).map(|()| {
                            Self::validate_segment_audio(segment, &segment_dir, video_validation)
                        })
                    })
                    .ok();
                let video = Self::finalize_segment_video(
                    recording,
                    segment,
                    &segment_dir,
                    video_validation,
                );
                (video, audio.map(|handle| handle.join()))
            });
            video?;
            audio_validations.push(match audio {
                Some(Ok(audio)) => audio?,
                Some(Err(_)) => {
                    return Err(RecoveryError::Validation(
                        "Studio audio finalization panicked".into(),
                    ));
                }
                None => {
                    Self::finalize_segment_audio(segment, &segment_dir)?;
                    Default::default()
                }
            });
        }

        let validating = Instant::now();
        for (segment, [mic_validation, system_validation]) in
            recording.recoverable_segments.iter().zip(audio_validations)
        {
            let dir = recording
                .project_path
                .join(format!("content/segments/segment-{}", segment.index));
            if video_validation == VideoValidation::Full {
                validate_recovery_track(
                    &dir.join("display.mp4"),
                    ffmpeg::media::Type::Video,
                    video_validation,
                )?;
            }
            for (fragments, audio_stem, kind, validated) in [
                (
                    segment.camera_fragments.as_deref(),
                    None,
                    ffmpeg::media::Type::Video,
                    None,
                ),
                (
                    segment.mic_fragments.as_deref(),
                    Some("audio-input"),
                    ffmpeg::media::Type::Audio,
                    mic_validation,
                ),
                (
                    segment.system_audio_fragments.as_deref(),
                    Some("system_audio"),
                    ffmpeg::media::Type::Audio,
                    system_validation,
                ),
            ] {
                if let Some(fragments) = fragments
                    && (kind != ffmpeg::media::Type::Video
                        || video_validation == VideoValidation::Full)
                {
                    match validated {
                        Some(result) => result?,
                        None => {
                            let name = audio_stem.map_or_else(
                                || "camera.mp4".to_string(),
                                |stem| finalized_audio_name(&dir, stem, fragments),
                            );
                            validate_recovery_track(&dir.join(name), kind, video_validation)?;
                        }
                    }
                }
            }
        }
        debug!(
            elapsed_ms = validating.elapsed().as_secs_f64() * 1000.0,
            "Studio finalization output tracks validated"
        );
        let meta = Self::build_recovered_meta(recording)?;

        let mut recording_meta = recording.meta.clone();
        recording_meta.inner = RecordingMetaInner::Studio(Box::new(meta.clone()));
        recording_meta
            .save_for_project()
            .map_err(|_| RecoveryError::MetaSave)?;

        Self::create_project_config(recording, &meta, purpose)?;

        finalization_info!(
            "{} at {:?}",
            purpose.success_message(),
            recording.project_path
        );

        Ok(RecoveredRecording {
            project_path: recording.project_path.clone(),
            meta,
        })
    }

    pub fn finalize_to_progressive_mp4(
        fragmented_dir: &Path,
        output: &Path,
    ) -> Result<PathBuf, RecoveryError> {
        Self::finalize_to_progressive_mp4_with_health(fragmented_dir, output, None)
    }

    pub fn validate_instant_output(
        project_path: &Path,
        required_audio: bool,
    ) -> Result<PathBuf, RecoveryError> {
        let content = project_path.join("content");
        let output = content.join("output.mp4");
        for path in [project_path, content.as_path(), output.as_path()] {
            reject_recovery_link(&path.symlink_metadata()?)?;
        }
        Self::require_no_track_failure(project_path)?;
        validate_recovered_track(&output, ffmpeg::media::Type::Video)?;
        probe_video_seek_points(&output, EXPORT_SEEK_PROBE_SAMPLE_COUNT)
            .map_err(RecoveryError::UnplayableVideo)?;
        let input = ffmpeg::format::input(&output)
            .map_err(|error| RecoveryError::Validation(error.to_string()))?;
        let has_audio = input.streams().best(ffmpeg::media::Type::Audio).is_some();
        drop(input);
        if required_audio || has_audio {
            validate_recovered_track(&output, ffmpeg::media::Type::Audio)?;
        }
        Ok(output)
    }

    pub fn finalize_instant_output(
        display_dir: &Path,
        audio_dir: &Path,
        output: &Path,
    ) -> Result<PathBuf, RecoveryError> {
        Self::finalize_instant_output_with_completion(display_dir, audio_dir, output, None)
    }

    pub fn finalize_completed_instant_output(
        display_dir: &Path,
        audio_dir: &Path,
        output: &Path,
        completion: crate::instant_recording::CleanInstantRecording,
    ) -> Result<PathBuf, RecoveryError> {
        Self::finalize_instant_output_with_completion(
            display_dir,
            audio_dir,
            output,
            Some(completion.into_parts()),
        )
    }

    fn finalize_instant_output_with_completion(
        display_dir: &Path,
        audio_dir: &Path,
        output: &Path,
        completion: Option<(PathBuf, bool)>,
    ) -> Result<PathBuf, RecoveryError> {
        Self::finalize_instant_output_with(
            display_dir,
            audio_dir,
            output,
            completion,
            |source, destination| std::fs::rename(source, destination),
            |workspace| std::fs::remove_dir_all(workspace),
        )
    }

    fn finalize_instant_output_with(
        display_dir: &Path,
        audio_dir: &Path,
        output: &Path,
        completion: Option<(PathBuf, bool)>,
        publish: impl FnOnce(&Path, &Path) -> std::io::Result<()>,
        cleanup: impl FnOnce(&Path) -> std::io::Result<()>,
    ) -> Result<PathBuf, RecoveryError> {
        let content = output
            .parent()
            .ok_or_else(|| RecoveryError::Validation("Instant output has no parent".into()))?;
        if display_dir.parent() != Some(content) || audio_dir.parent() != Some(content) {
            return Err(RecoveryError::Validation(
                "Instant tracks must share the output directory".into(),
            ));
        }
        let project = content
            .parent()
            .ok_or_else(|| RecoveryError::Validation("Instant content has no project".into()))?;
        if content.file_name().is_none_or(|name| name != "content") {
            return Err(RecoveryError::Validation(
                "Instant tracks must be in project content".into(),
            ));
        }
        let (video_validation, completed_audio) = match completion {
            Some((completed_project, expected_audio)) => {
                if completed_project != project {
                    return Err(RecoveryError::Validation(
                        "Instant completion belongs to another recording".into(),
                    ));
                }
                if display_dir != content.join("display")
                    || audio_dir != content.join("audio")
                    || output != content.join("output.mp4")
                {
                    return Err(RecoveryError::Validation(
                        "Instant completion must use the recorded track and output paths".into(),
                    ));
                }
                (VideoValidation::Bounded, expected_audio)
            }
            None => (VideoValidation::Full, false),
        };
        let staging_durability = match video_validation {
            VideoValidation::Full => RecoveryCopyDurability::Durable,
            VideoValidation::Bounded => RecoveryCopyDurability::Deferred,
        };
        Self::require_no_track_failure(project)?;
        let _lock = RecoveryLock::acquire(project)?;
        let before = recovery_snapshot(project)?;
        let mut expected_audio = completed_audio || audio_dir.try_exists()?;
        if project.join("recording-meta.json").try_exists()? {
            let meta = RecordingMeta::load_for_project(project)
                .map_err(|error| RecoveryError::Validation(error.to_string()))?;
            match meta.inner {
                RecordingMetaInner::Instant(cap_project::InstantRecordingMeta::Failed {
                    error,
                }) => {
                    return Err(RecoveryError::RequiredTrackFailure(error));
                }
                RecordingMetaInner::Instant(cap_project::InstantRecordingMeta::Complete {
                    sample_rate,
                    ..
                }) => {
                    expected_audio |= sample_rate.is_some();
                }
                RecordingMetaInner::Instant(_) => {}
                _ => {
                    return Err(RecoveryError::Validation(
                        "Instant output requires Instant metadata".into(),
                    ));
                }
            }
        }
        let workspace = project.join(format!(".recovery-{}", uuid::Uuid::new_v4()));
        create_private_recovery_dir(&workspace)?;
        let staged = workspace.join("content");
        let result = (|| {
            copy_recovery_input_with_durability(content, &staged, staging_durability)?;
            validate_recovery_manifests(&staged)?;
            let display = staged.join(
                display_dir
                    .file_name()
                    .ok_or_else(|| RecoveryError::Validation("Missing display name".into()))?,
            );
            let audio = staged.join(
                audio_dir
                    .file_name()
                    .ok_or_else(|| RecoveryError::Validation("Missing audio name".into()))?,
            );
            let final_output = staged.join(
                output
                    .file_name()
                    .ok_or_else(|| RecoveryError::Validation("Missing output name".into()))?,
            );
            if final_output.is_file()
                && let Ok(input) = ffmpeg::format::input(&final_output)
            {
                expected_audio |= input.streams().best(ffmpeg::media::Type::Audio).is_some();
            }
            if expected_audio && !audio.is_dir() {
                return Err(RecoveryError::Validation(
                    "Missing required Instant audio".into(),
                ));
            }
            Self::rescue_pending_tmp_fragments(&display, None, false);
            let video = Self::find_complete_fragments_with_init(&display);
            if video_validation == VideoValidation::Full || video.init_segment.is_none() {
                validate_recovery_video_inputs(
                    &video.fragments,
                    video.init_segment.as_deref(),
                    &workspace,
                    video_validation,
                )?;
            }
            let final_audio_validation = Self::finalize_instant_staged(
                &display,
                &audio,
                &final_output,
                video_validation,
                expected_audio,
            )?;
            if video_validation == VideoValidation::Full {
                validate_recovery_track(
                    &final_output,
                    ffmpeg::media::Type::Video,
                    video_validation,
                )?;
            }
            if expected_audio {
                match final_audio_validation {
                    Some(result) => result?,
                    None => validate_recovered_track(&final_output, ffmpeg::media::Type::Audio)?,
                }
            }
            sync_recovery_input(&final_output)?;
            Self::require_no_track_failure(project)?;
            if recovery_snapshot(project)? != before {
                return Err(RecoveryError::Validation(
                    "Instant recording changed during finalization".into(),
                ));
            }
            if output.try_exists()? {
                copy_recovery_input(output, &workspace.join("original-output.mp4"))?;
            }
            publish(&final_output, output)?;
            Ok(output.to_path_buf())
        })();
        if let Err(error) = cleanup(&workspace) {
            warn!(path = %workspace.display(), %error, "Could not remove temporary Instant finalization workspace");
        }
        result
    }

    fn finalize_instant_staged(
        display_dir: &Path,
        audio_dir: &Path,
        output: &Path,
        video_validation: VideoValidation,
        validate_output_audio: bool,
    ) -> Result<Option<Result<(), RecoveryError>>, RecoveryError> {
        if !audio_dir.exists() {
            Self::finalize_to_progressive_mp4_with_validation(
                display_dir,
                output,
                None,
                video_validation,
                false,
            )?;
            return Ok(None);
        }

        Self::rescue_pending_tmp_fragments(audio_dir, None, false);
        let audio_info = Self::find_complete_fragments_with_init(audio_dir);
        if audio_info.fragments.is_empty() {
            return Err(RecoveryError::Validation(
                "Required Instant audio has no recoverable fragments".into(),
            ));
        }

        let parent = output.parent().unwrap_or_else(|| Path::new("."));
        std::fs::create_dir_all(parent)?;
        let stem = output
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("instant");
        let video_output = parent.join(format!("{stem}.video.mp4"));
        let audio_output = parent.join(format!("{stem}.audio.mp4"));
        let merged_output = parent.join(format!("{stem}.merged.mp4"));

        let result = (|| {
            let finalize_audio = || {
                let validated = validate_recovery_track_inputs(
                    &audio_info.fragments,
                    audio_info.init_segment.as_deref(),
                    parent,
                    ffmpeg::media::Type::Audio,
                    VideoValidation::Full,
                );
                validated.map(|()| {
                    Self::finalize_audio_fragments_to_progressive_mp4(
                        &audio_info.fragments,
                        audio_info.init_segment.as_deref(),
                        &audio_output,
                        "audio",
                    )
                })
            };
            let (audio, video) = std::thread::scope(|scope| {
                let audio = std::thread::Builder::new()
                    .name("instant-audio-finalize".into())
                    .stack_size(AUDIO_FINALIZE_STACK_SIZE)
                    .spawn_scoped(scope, finalize_audio)
                    .ok();
                let video = Self::finalize_to_progressive_mp4_with_validation(
                    display_dir,
                    &video_output,
                    None,
                    video_validation,
                    false,
                );
                let audio = match audio {
                    Some(handle) => handle.join().unwrap_or_else(|_| {
                        Err(RecoveryError::Validation(
                            "Instant audio finalization panicked".into(),
                        ))
                    }),
                    None => finalize_audio(),
                };
                (audio, video)
            });
            let audio_concat = audio?;
            video?;
            audio_concat?;
            merge_video_audio(&video_output, &audio_output, &merged_output)
                .map_err(RecoveryError::MediaMerge)?;
            let (video, audio) = std::thread::scope(|scope| {
                let audio = validate_output_audio
                    .then(|| {
                        std::thread::Builder::new()
                            .name("instant-audio-validate".into())
                            .stack_size(AUDIO_FINALIZE_STACK_SIZE)
                            .spawn_scoped(scope, || {
                                validate_recovered_track(&merged_output, ffmpeg::media::Type::Audio)
                            })
                            .ok()
                    })
                    .flatten();
                let video = Self::check_required_video(&merged_output, "display", video_validation);
                (video, audio.and_then(|handle| handle.join().ok()))
            });
            let audio = match video? {
                Ok(()) => audio,
                Err(seek_error) => {
                    Self::normalize_required_video(
                        &merged_output,
                        "display",
                        video_validation,
                        &seek_error,
                    )?;
                    None
                }
            };
            replace_file(&merged_output, output)?;
            Ok(audio)
        })();

        for path in [&video_output, &audio_output, &merged_output] {
            if path.exists() && path != output {
                let _ = std::fs::remove_file(path);
            }
        }

        result
    }

    pub fn finalize_to_progressive_mp4_with_health(
        fragmented_dir: &Path,
        output: &Path,
        health_tx: Option<&HealthSender>,
    ) -> Result<PathBuf, RecoveryError> {
        Self::finalize_to_progressive_mp4_with_validation(
            fragmented_dir,
            output,
            health_tx,
            VideoValidation::Full,
            true,
        )
    }

    fn finalize_to_progressive_mp4_with_validation(
        fragmented_dir: &Path,
        output: &Path,
        health_tx: Option<&HealthSender>,
        video_validation: VideoValidation,
        recover_complete_prefixes: bool,
    ) -> Result<PathBuf, RecoveryError> {
        Self::rescue_pending_tmp_fragments(fragmented_dir, health_tx, recover_complete_prefixes);

        let info = Self::find_complete_fragments_with_init(fragmented_dir);
        let respawn_groups =
            Self::collect_respawn_groups(fragmented_dir, health_tx, recover_complete_prefixes);

        if respawn_groups.is_empty() {
            Self::finalize_fragments_to_progressive_mp4(
                &info.fragments,
                info.init_segment.as_deref(),
                output,
                "display",
                video_validation,
            )?;
            return Ok(output.to_path_buf());
        }

        let mut group_outputs: Vec<PathBuf> = Vec::new();
        let mut temp_paths: Vec<PathBuf> = Vec::new();
        let stem = output
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("recovered");
        let parent = output.parent().unwrap_or_else(|| Path::new("."));

        if !info.fragments.is_empty() {
            let main_tmp = parent.join(format!("{stem}.main.mp4"));
            Self::finalize_fragments_to_progressive_mp4(
                &info.fragments,
                info.init_segment.as_deref(),
                &main_tmp,
                "display",
                video_validation,
            )?;
            temp_paths.push(main_tmp.clone());
            group_outputs.push(main_tmp);
        }

        for (n, init, fragments) in respawn_groups {
            let group_tmp = parent.join(format!("{stem}.respawn-{n}.mp4"));
            Self::finalize_fragments_to_progressive_mp4(
                &fragments,
                Some(init.as_path()),
                &group_tmp,
                &format!("display respawn-{n}"),
                video_validation,
            )?;
            temp_paths.push(group_tmp.clone());
            group_outputs.push(group_tmp);
        }

        let concat_result = if group_outputs.len() == 1 {
            std::fs::rename(&group_outputs[0], output)
                .map_err(|e| RecoveryError::VideoConcat(cap_enc_ffmpeg::remux::RemuxError::Io(e)))
        } else {
            concatenate_video_fragments_on_timeline(&group_outputs, output)
                .map_err(RecoveryError::VideoConcat)
        };

        for tmp in &temp_paths {
            if tmp.exists() && tmp != output {
                let _ = std::fs::remove_file(tmp);
            }
        }

        concat_result?;
        Self::validate_required_video(output, "display", video_validation)?;

        Ok(output.to_path_buf())
    }

    fn finalize_fragments_to_progressive_mp4(
        fragments: &[PathBuf],
        init_segment: Option<&Path>,
        output: &Path,
        label: &str,
        video_validation: VideoValidation,
    ) -> Result<(), RecoveryError> {
        if fragments.is_empty() {
            return Err(RecoveryError::NoRecoverableSegments);
        }

        if let Some(init_path) = init_segment {
            finalization_info!(
                "Concatenating {} M4S {label} segments with init to {:?}",
                fragments.len(),
                output
            );
            match video_validation {
                VideoValidation::Bounded => {
                    concatenate_m4s_segments_with_init_validated(init_path, fragments, output)
                }
                VideoValidation::Full => {
                    concatenate_m4s_segments_with_init(init_path, fragments, output)
                }
            }
            .map_err(RecoveryError::VideoConcat)?;
        } else {
            finalization_info!(
                "Concatenating {} {label} fragments to {:?}",
                fragments.len(),
                output
            );
            concatenate_video_fragments(fragments, output).map_err(RecoveryError::VideoConcat)?;
        }

        Self::validate_required_video(output, label, video_validation)?;
        Ok(())
    }

    fn finalize_audio_fragments_to_progressive_mp4(
        fragments: &[PathBuf],
        init_segment: Option<&Path>,
        output: &Path,
        label: &str,
    ) -> Result<(), RecoveryError> {
        if fragments.is_empty() {
            return Err(RecoveryError::NoRecoverableSegments);
        }

        if let Some(init_path) = init_segment {
            finalization_info!(
                "Concatenating {} M4S {label} segments with init to {:?}",
                fragments.len(),
                output
            );
            concatenate_m4s_segments_with_init(init_path, fragments, output)
                .map_err(RecoveryError::AudioConcat)?;
        } else {
            finalization_info!(
                "Concatenating {} {label} fragments to {:?}",
                fragments.len(),
                output
            );
            concatenate_video_fragments(fragments, output).map_err(RecoveryError::AudioConcat)?;
        }

        Ok(())
    }

    fn validate_required_video(
        path: &Path,
        label: &str,
        video_validation: VideoValidation,
    ) -> Result<(), RecoveryError> {
        if let Err(seek_error) = Self::check_required_video(path, label, video_validation)? {
            Self::normalize_required_video(path, label, video_validation, &seek_error)?;
        }
        Ok(())
    }

    fn check_required_video(
        path: &Path,
        label: &str,
        video_validation: VideoValidation,
    ) -> Result<Result<(), String>, RecoveryError> {
        finalization_info!("Validating finalized {} video: {:?}", label, path);

        if video_validation == VideoValidation::Full {
            Self::ensure_video_decodes(path, label)?;
        }

        let (seek_result, track_result) = std::thread::scope(|scope| {
            let track = (video_validation == VideoValidation::Bounded).then(|| {
                scope.spawn(|| {
                    validate_recovery_track(path, ffmpeg::media::Type::Video, video_validation)
                })
            });
            let seek = probe_video_seek_points(path, EXPORT_SEEK_PROBE_SAMPLE_COUNT);
            let track = track.map(|handle| {
                handle.join().unwrap_or_else(|_| {
                    Err(RecoveryError::Validation(format!(
                        "{label} video track validation panicked"
                    )))
                })
            });
            (seek, track)
        });

        match seek_result {
            Ok(()) => {
                if let Some(track_result) = track_result {
                    track_result?;
                }
                Ok(Ok(()))
            }
            Err(seek_error) => Ok(Err(seek_error)),
        }
    }

    fn normalize_required_video(
        path: &Path,
        label: &str,
        video_validation: VideoValidation,
        seek_error: &str,
    ) -> Result<(), RecoveryError> {
        finalization_info!(
            "Finalized {} video failed seek validation, normalizing via remux: {}",
            label,
            seek_error
        );
        Self::normalize_recovered_video(path, label)?;
        if video_validation == VideoValidation::Bounded {
            validate_recovery_track(path, ffmpeg::media::Type::Video, video_validation)?;
        }
        Ok(())
    }

    fn ensure_video_decodes(path: &Path, label: &str) -> Result<(), RecoveryError> {
        match probe_video_can_decode(path) {
            Ok(true) => Ok(()),
            Ok(false) => Err(RecoveryError::UnplayableVideo(format!(
                "{label} video has no decodable frames: {path:?}"
            ))),
            Err(e) => Err(RecoveryError::UnplayableVideo(format!(
                "{label} video validation failed for {path:?}: {e}"
            ))),
        }
    }

    fn normalize_recovered_video(path: &Path, label: &str) -> Result<(), RecoveryError> {
        let normalized_path = path.with_extension("normalized.mp4");

        remux_file(path, &normalized_path).map_err(RecoveryError::VideoConcat)?;

        replace_file(&normalized_path, path)?;

        Self::ensure_video_decodes(path, label)?;

        probe_video_seek_points(path, EXPORT_SEEK_PROBE_SAMPLE_COUNT).map_err(|e| {
            RecoveryError::UnplayableVideo(format!(
                "{label} video seek validation failed for {path:?}: {e}"
            ))
        })?;

        finalization_info!(
            "Finalized {} video validation passed after normalization",
            label
        );

        Ok(())
    }

    fn build_recovered_meta(
        recording: &IncompleteRecording,
    ) -> Result<StudioRecordingMeta, RecoveryError> {
        let original_segments = match recording.meta.studio_meta() {
            Some(StudioRecordingMeta::MultipleSegments { inner, .. }) => Some(&inner.segments),
            _ => None,
        };

        let segments: Vec<MultipleSegment> = recording
            .recoverable_segments
            .iter()
            .map(|seg| {
                let segment_index = seg.index;
                let segment_base = format!("content/segments/segment-{segment_index}");
                let segment_dir = recording.project_path.join(&segment_base);

                let original_segment =
                    original_segments.and_then(|segs| segs.get(segment_index as usize));

                let display_path = segment_dir.join("display.mp4");
                // Decoders number frames on this rate. The file's average rate
                // is far lower for a mostly static screen (11 fps for a 120 fps
                // capture), and on that coarse grid playback and export drop
                // every picture shorter than one step.
                let fps = original_segment
                    .map(|s| s.display.fps)
                    .filter(|fps| *fps > 0)
                    .or_else(|| get_video_base_fps(&display_path))
                    .unwrap_or(30);

                let cursor_path = segment_dir.join("cursor.json");
                let keyboard_path = {
                    let binary = segment_dir.join(cap_project::KEYBOARD_EVENTS_FILE_NAME);
                    if binary.exists() {
                        binary
                    } else {
                        segment_dir.join(cap_project::LEGACY_KEYBOARD_EVENTS_FILE_NAME)
                    }
                };

                let persisted = persisted_start_times(&segment_dir);
                let display_start_time = original_segment
                    .and_then(|s| s.display.start_time)
                    .or(persisted.map(|times| times.display));

                let get_start_time_or_fallback = |original_time: Option<f64>| -> Option<f64> {
                    start_time_or_display_fallback(original_time, display_start_time)
                };

                MultipleSegment {
                    display: VideoMeta {
                        path: RelativePathBuf::from(format!("{segment_base}/display.mp4")),
                        fps,
                        start_time: display_start_time,
                        device_id: original_segment.and_then(|s| s.display.device_id.clone()),
                    },
                    camera: if seg.camera_fragments.is_some() {
                        Some(VideoMeta {
                            path: RelativePathBuf::from(format!("{segment_base}/camera.mp4")),
                            fps: original_segment
                                .and_then(|s| s.camera.as_ref())
                                .map(|c| c.fps)
                                .unwrap_or(30),
                            start_time: get_start_time_or_fallback(
                                original_segment
                                    .and_then(|s| s.camera.as_ref())
                                    .and_then(|c| c.start_time)
                                    .or(persisted.and_then(|times| times.camera)),
                            ),
                            device_id: original_segment
                                .and_then(|s| s.camera.as_ref())
                                .and_then(|c| c.device_id.clone()),
                        })
                    } else {
                        None
                    },
                    mic: {
                        if seg.mic_fragments.is_some() {
                            Some(AudioMeta {
                                path: RelativePathBuf::from(format!(
                                    "{segment_base}/{}",
                                    finalized_audio_name(
                                        &segment_dir,
                                        "audio-input",
                                        seg.mic_fragments.as_deref().unwrap_or_default()
                                    )
                                )),
                                start_time: get_start_time_or_fallback(
                                    original_segment
                                        .and_then(|s| s.mic.as_ref())
                                        .and_then(|m| m.start_time)
                                        .or(persisted.and_then(|times| times.mic)),
                                ),
                                device_id: original_segment
                                    .and_then(|s| s.mic.as_ref())
                                    .and_then(|m| m.device_id.clone()),
                                gap_summary: None,
                                digital_silence_ms: original_segment
                                    .and_then(|s| s.mic.as_ref())
                                    .and_then(|m| m.digital_silence_ms),
                            })
                        } else {
                            None
                        }
                    },
                    system_audio: {
                        if seg.system_audio_fragments.is_some() {
                            Some(AudioMeta {
                                path: RelativePathBuf::from(format!(
                                    "{segment_base}/{}",
                                    finalized_audio_name(
                                        &segment_dir,
                                        "system_audio",
                                        seg.system_audio_fragments.as_deref().unwrap_or_default()
                                    )
                                )),
                                start_time: get_start_time_or_fallback(
                                    original_segment
                                        .and_then(|s| s.system_audio.as_ref())
                                        .and_then(|a| a.start_time)
                                        .or(persisted.and_then(|times| times.system_audio)),
                                ),
                                device_id: original_segment
                                    .and_then(|s| s.system_audio.as_ref())
                                    .and_then(|a| a.device_id.clone()),
                                gap_summary: None,
                                digital_silence_ms: None,
                            })
                        } else {
                            None
                        }
                    },
                    cursor: if cursor_path.exists() {
                        Some(RelativePathBuf::from(format!("{segment_base}/cursor.json")))
                    } else {
                        None
                    },
                    keyboard: if keyboard_path.exists() {
                        keyboard_path.file_name().map(|file_name| {
                            RelativePathBuf::from(format!(
                                "{segment_base}/{}",
                                file_name.to_string_lossy()
                            ))
                        })
                    } else {
                        None
                    },
                    display_notch: original_segment.and_then(|s| s.display_notch),
                }
            })
            .collect();

        let existing_cursors = Self::load_existing_cursors(&recording.project_path);

        Ok(StudioRecordingMeta::MultipleSegments {
            inner: MultipleSegments {
                segments,
                cursors: existing_cursors,
                status: Some(StudioRecordingStatus::Complete),
            },
        })
    }

    fn create_project_config(
        recording: &IncompleteRecording,
        meta: &StudioRecordingMeta,
        purpose: RecoveryPurpose,
    ) -> Result<(), RecoveryError> {
        let StudioRecordingMeta::MultipleSegments { inner, .. } = meta else {
            return Ok(());
        };

        let timeline_segments: Vec<TimelineSegment> = inner
            .segments
            .iter()
            .enumerate()
            .filter_map(|(i, segment)| {
                let display_path = recording.project_path.join(segment.display.path.as_str());

                let duration = get_media_duration(&display_path)
                    .map(|d| d.as_secs_f64())
                    .unwrap_or_else(|| {
                        let fps = segment.display.fps as f64;
                        if fps > 0.0 {
                            recording.estimated_duration.as_secs_f64()
                                / recording.recoverable_segments.len() as f64
                        } else {
                            5.0
                        }
                    });

                if duration <= 0.0 {
                    return None;
                }

                Some(TimelineSegment {
                    recording_clip: i as u32,
                    start: 0.0,
                    end: duration,
                    timescale: 1.0,
                    name: None,
                    speed_audio_mode: None,
                    hide_cursor: None,
                    volume: None,
                })
            })
            .collect();

        if timeline_segments.len() != inner.segments.len() || timeline_segments.is_empty() {
            warn!("No valid timeline segments could be created");
            return Err(RecoveryError::Validation(
                "No valid recovery timeline".into(),
            ));
        }

        let mut config = match ProjectConfiguration::load(&recording.project_path) {
            Ok(config) => config,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
                ProjectConfiguration::default()
            }
            Err(error) => return Err(error.into()),
        };

        config.timeline = Some(TimelineConfiguration {
            segments: timeline_segments,
            transitions: Vec::new(),
            zoom_segments: Vec::new(),
            scene_segments: Vec::new(),
            style_segments: Vec::new(),
            image_segments: Vec::new(),
            mask_segments: Vec::new(),
            text_segments: Vec::new(),
            caption_segments: Vec::new(),
            keyboard_segments: Vec::new(),
            audio_segments: Vec::new(),
            camera3d_segments: Vec::new(),
        });

        config
            .write(&recording.project_path)
            .map_err(RecoveryError::Io)?;

        finalization_info!("{}", purpose.timeline_message());

        Ok(())
    }

    fn load_existing_cursors(project_path: &Path) -> Cursors {
        let cursors_dir = project_path.join("content/cursors");
        if !cursors_dir.exists() {
            return Cursors::default();
        }

        if let Ok(meta) = RecordingMeta::load_for_project(project_path)
            && let Some(StudioRecordingMeta::MultipleSegments { inner, .. }) = meta.studio_meta()
            && !inner.cursors.is_empty()
        {
            return inner.cursors.clone();
        }

        Self::scan_cursor_images(&cursors_dir)
    }

    fn scan_cursor_images(cursors_dir: &Path) -> Cursors {
        let Ok(entries) = std::fs::read_dir(cursors_dir) else {
            return Cursors::default();
        };

        let mut cursors = std::collections::HashMap::new();

        for entry in entries.flatten() {
            let path = entry.path();
            if path.extension().map(|e| e == "png").unwrap_or(false)
                && let Some(file_name) = path.file_stem().and_then(|s| s.to_str())
                && let Some(id_str) = file_name.strip_prefix("cursor_")
                && let Some(full_file_name) = path.file_name().and_then(|n| n.to_str())
            {
                let relative_path = RelativePathBuf::from("content/cursors").join(full_file_name);

                cursors.insert(
                    id_str.to_string(),
                    cap_project::CursorMeta {
                        image_path: relative_path,
                        hotspot: cap_project::XY::new(0.0, 0.0),
                        shape: None,
                    },
                );

                finalization_info!(
                    "Loaded cursor {} from image file: {:?}",
                    id_str,
                    path.file_name()
                );
            }
        }

        if cursors.is_empty() {
            Cursors::default()
        } else {
            Cursors::Correct(cursors)
        }
    }

    pub fn discard(recording: &IncompleteRecording) -> std::io::Result<()> {
        warn!(
            "Discarding incomplete recording at {:?}",
            recording.project_path
        );
        std::fs::remove_dir_all(&recording.project_path)
    }

    pub fn mark_needs_remux(project_path: &Path) -> Result<(), RecoveryError> {
        let mut meta =
            RecordingMeta::load_for_project(project_path).map_err(|_| RecoveryError::MetaSave)?;

        if let RecordingMetaInner::Studio(studio) = &mut meta.inner
            && let StudioRecordingMeta::MultipleSegments { inner, .. } = studio.as_mut()
        {
            inner.status = Some(StudioRecordingStatus::NeedsRemux);
            meta.save_for_project()
                .map_err(|_| RecoveryError::MetaSave)?;
        }

        Ok(())
    }

    fn mark_unrecoverable(project_path: &Path, meta: &RecordingMeta) {
        let mut updated_meta = meta.clone();

        let status_updated = match &mut updated_meta.inner {
            RecordingMetaInner::Studio(studio) => {
                if let StudioRecordingMeta::MultipleSegments { inner, .. } = studio.as_mut() {
                    if matches!(inner.status, Some(StudioRecordingStatus::Failed { .. })) {
                        debug!(
                            "Recording already failed before startup cleanup, preserving original status: {:?}",
                            project_path
                        );
                        return;
                    }

                    inner.status = Some(StudioRecordingStatus::Failed {
                        error: "No recoverable segments found".to_string(),
                    });
                    true
                } else {
                    false
                }
            }
            _ => false,
        };

        if status_updated {
            if let Err(e) = updated_meta.save_for_project() {
                warn!(
                    "Failed to mark recording as unrecoverable at {:?}: {}",
                    project_path, e
                );
            } else {
                debug!(
                    "Marked stale recording as failed because no media fragments were present: {:?}",
                    project_path
                );
            }
        }
    }
}

fn create_private_recovery_dir(path: &Path) -> std::io::Result<()> {
    let builder = std::fs::DirBuilder::new();
    #[cfg(unix)]
    let builder = {
        use std::os::unix::fs::DirBuilderExt;
        let mut builder = builder;
        builder.mode(0o700);
        builder
    };
    builder.create(path)
}

fn recovery_child_path(dir: &Path, name: &str) -> Option<PathBuf> {
    let child = Path::new(name);
    if child.as_os_str().is_empty()
        || !child
            .components()
            .all(|component| matches!(component, std::path::Component::Normal(_)))
    {
        return None;
    }
    Some(dir.join(child))
}

fn validate_recovery_manifests(dir: &Path) -> Result<(), RecoveryError> {
    for entry in std::fs::read_dir(dir)? {
        let path = entry?.path();
        if path.is_dir() {
            validate_recovery_manifests(&path)?;
        } else if path.file_name().is_some_and(|name| name == "manifest.json") {
            let raw = std::fs::read(&path)?;
            let Ok(manifest) = serde_json::from_slice::<serde_json::Value>(&raw) else {
                continue;
            };
            let parent = path
                .parent()
                .ok_or_else(|| RecoveryError::Validation("Manifest has no parent".into()))?;
            if let Some(init) = manifest
                .get("init_segment")
                .and_then(serde_json::Value::as_str)
            {
                let init = recovery_child_path(parent, init)
                    .ok_or_else(|| RecoveryError::Validation("Invalid init path".into()))?;
                if !init.is_file() {
                    return Err(RecoveryError::Validation(
                        "Missing declared init segment".into(),
                    ));
                }
            }
            for fragment in manifest
                .get("segments")
                .or_else(|| manifest.get("fragments"))
                .and_then(serde_json::Value::as_array)
                .into_iter()
                .flatten()
            {
                let Some(name) = fragment.get("path").and_then(serde_json::Value::as_str) else {
                    continue;
                };
                let path = recovery_child_path(parent, name).ok_or_else(|| {
                    RecoveryError::Validation("Invalid manifest fragment path".into())
                })?;
                if fragment
                    .get("is_complete")
                    .and_then(serde_json::Value::as_bool)
                    != Some(true)
                {
                    continue;
                }
                let metadata = path.symlink_metadata()?;
                if !metadata.is_file()
                    || fragment
                        .get("file_size")
                        .and_then(serde_json::Value::as_u64)
                        .is_some_and(|size| size != metadata.len())
                    || (path.extension().is_some_and(|ext| ext == "m4s")
                        && !RecoveryManager::is_m4s_complete(&path))
                {
                    return Err(RecoveryError::Validation(format!(
                        "Invalid declared complete fragment: {}",
                        path.display()
                    )));
                }
            }
        }
    }
    Ok(())
}

fn validate_recovery_video_inputs(
    fragments: &[PathBuf],
    init: Option<&Path>,
    workspace: &Path,
    video_validation: VideoValidation,
) -> Result<(), RecoveryError> {
    validate_recovery_track_inputs(
        fragments,
        init,
        workspace,
        ffmpeg::media::Type::Video,
        video_validation,
    )
}

fn legacy_omitted_tracks(
    meta: &RecordingMeta,
    project_path: &Path,
) -> Result<Vec<(usize, &'static str)>, RecoveryError> {
    let raw = match std::fs::read(project_path.join("recording-diagnostics.json")) {
        Ok(raw) => raw,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(error) => return Err(error.into()),
    };
    let diagnostics = serde_json::from_slice(&raw)?;
    Ok(meta
        .studio_meta()
        .and_then(|studio| studio.legacy_omitted_track_failures(&diagnostics))
        .unwrap_or_default()
        .into_iter()
        .filter_map(|(index, track)| {
            let name = match track {
                "microphone" => "audio-input",
                "camera" => "camera",
                "systemAudio" => "system_audio",
                _ => return None,
            };
            Some((index, name))
        })
        .collect())
}

fn validate_recovery_track_inputs(
    fragments: &[PathBuf],
    init: Option<&Path>,
    workspace: &Path,
    kind: ffmpeg::media::Type,
    video_validation: VideoValidation,
) -> Result<(), RecoveryError> {
    if fragments.is_empty() {
        return Err(RecoveryError::NoRecoverableSegments);
    }
    if let Some(init) = init {
        let path = workspace.join(format!(".validate-{}.mp4", uuid::Uuid::new_v4()));
        let mut output = std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&path)?;
        for source in std::iter::once(init).chain(fragments.iter().map(PathBuf::as_path)) {
            std::io::copy(&mut std::fs::File::open(source)?, &mut output)?;
        }
        if video_validation == VideoValidation::Full {
            output.sync_all()?;
        }
        drop(output);
        validate_recovery_track(&path, kind, video_validation)?;
        std::fs::remove_file(path)?;
    } else {
        for path in fragments {
            validate_recovery_track(path, kind, video_validation)?;
        }
    }
    Ok(())
}

const RECOVERY_INPUTS: [&str; 4] = [
    "content",
    "recording-meta.json",
    "project-config.json",
    "recording-diagnostics.json",
];

enum HeldRecoveryLock {
    Owned { _lock: RecoveryLock },
    Shared(Arc<PreparingRecoveryLock>),
}

impl HeldRecoveryLock {
    fn new(lock: RecoveryLock, preparing: bool) -> Self {
        if preparing {
            let lock = retirement::RecoveryLease::new(lock);
            Self::Shared(Arc::new(lock))
        } else {
            Self::Owned { _lock: lock }
        }
    }
}

fn prepare_studio_source(
    recording: &IncompleteRecording,
    preparing: Option<&mut PreparingStudioJob>,
    lock: &HeldRecoveryLock,
) -> Option<RelocatableSource> {
    let job = preparing?;
    let HeldRecoveryLock::Shared(lock) = lock else {
        job.unavailable("The finalizer does not own a preparing source lease".into());
        return None;
    };
    let projected = job
        .claimed()
        .ok_or_else(|| "The stopped recording was already claimed".to_string())
        .and_then(|claim| preparing_projection::project(recording, claim))
        .and_then(|projection| {
            let source = RelocatableSource::new_with_owner(
                recording.project_path.join("content/segments"),
                lock.clone(),
            )
            .map_err(|error| error.to_string())?;
            Ok((source, projection))
        });
    match projected {
        Ok((source, projection)) => job.publish(source.clone(), projection).then_some(source),
        Err(error) => {
            job.unavailable(error);
            None
        }
    }
}

struct RecoveryLock {
    _file: std::fs::File,
    #[cfg(unix)]
    owner_pid: libc::pid_t,
}

impl RecoveryLock {
    fn acquire(project: &Path) -> Result<Self, RecoveryError> {
        Self::acquire_with(project, reconcile_recovery_publication)
    }

    fn acquire_for_preparing_preview(project: &Path) -> Result<Self, RecoveryError> {
        Self::acquire_with(project, |project| {
            match project.join(RECOVERY_PUBLICATION).symlink_metadata() {
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
                Err(error) => Err(error.into()),
                Ok(_) => Err(RecoveryError::Validation(
                    "Interrupted publication must be reconciled after preparing preview readers stop"
                        .into(),
                )),
            }
        })
    }

    fn acquire_with(
        project: &Path,
        reconcile: impl FnOnce(&Path) -> Result<(), RecoveryError>,
    ) -> Result<Self, RecoveryError> {
        reject_recovery_link(&project.symlink_metadata()?)?;
        let path = project.join(".recovery.lock");
        let mut options = std::fs::OpenOptions::new();
        options.read(true).write(true).create(true).truncate(false);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            options
                .mode(0o600)
                .custom_flags(libc::O_NOFOLLOW | libc::O_CLOEXEC);
        }
        #[cfg(windows)]
        {
            use std::os::windows::fs::OpenOptionsExt;
            const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
            options
                .share_mode(0)
                .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);
        }
        let file = options.open(&path)?;
        let metadata = file.metadata()?;
        reject_recovery_link(&metadata)?;
        if !metadata.is_file() || metadata.len() != 0 {
            return Err(RecoveryError::Validation(
                "Invalid recovery lock file".into(),
            ));
        }
        #[cfg(unix)]
        {
            use std::os::fd::AsRawFd;
            use std::os::unix::fs::MetadataExt;
            if metadata.nlink() != 1 || metadata.uid() != unsafe { libc::geteuid() } {
                return Err(RecoveryError::Validation(
                    "Recovery lock is not exclusively owned".into(),
                ));
            }
            if unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) } != 0 {
                return Err(std::io::Error::last_os_error().into());
            }
        }
        let lock = Self {
            _file: file,
            #[cfg(unix)]
            owner_pid: unsafe { libc::getpid() },
        };
        if let Err(error) = reconcile(project) {
            warn!(path = %project.display(), %error, "Interrupted recovery publication requires attention; all files retained");
            return Err(error);
        }
        Ok(lock)
    }
}

impl RecoveryLock {
    /// Whether this process took the lock: on unix a forked child inherits the
    /// descriptor but not the lock's ownership. Windows has no fork.
    fn owned_by_this_process(&self) -> bool {
        #[cfg(unix)]
        {
            self.owner_pid == unsafe { libc::getpid() }
        }
        #[cfg(not(unix))]
        {
            true
        }
    }
}

#[cfg(unix)]
impl Drop for RecoveryLock {
    fn drop(&mut self) {
        use std::os::fd::AsRawFd;

        // CLOEXEC still leaves a fork-to-exec window that can outlive this guard.
        if self.owner_pid == unsafe { libc::getpid() }
            && unsafe { libc::flock(self._file.as_raw_fd(), libc::LOCK_UN) } != 0
        {
            warn!(error = %std::io::Error::last_os_error(), "Failed to release recovery lock");
        }
    }
}

fn reject_recovery_link(metadata: &std::fs::Metadata) -> Result<(), RecoveryError> {
    #[cfg(windows)]
    {
        use std::os::windows::fs::MetadataExt;
        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x400;
        if metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
            return Err(RecoveryError::Validation(
                "Recovery input is a reparse point".into(),
            ));
        }
    }
    if metadata.file_type().is_symlink() {
        return Err(RecoveryError::Validation(
            "Recovery input is a symbolic link".into(),
        ));
    }
    Ok(())
}

/// On exFAT/FAT volumes macOS keeps each file's extended attributes (every
/// file Cap writes gets `com.apple.provenance`) in a visible `._<name>`
/// AppleDouble sibling, and creates the destination's own sibling as soon as a
/// copy creates `<name>`. Copying the source's sibling then fails with EEXIST,
/// every time: https://github.com/CapSoftware/Cap/issues/2386. Cap never
/// writes `._` names, so these entries are filesystem bookkeeping, not
/// recording data.
fn is_apple_double(name: &std::ffi::OsStr) -> bool {
    name.as_encoded_bytes().starts_with(b"._")
}

fn copy_recovery_input(source: &Path, destination: &Path) -> Result<(), RecoveryError> {
    copy_recovery_input_with_durability(source, destination, RecoveryCopyDurability::Durable)
}

fn copy_recovery_input_with_durability(
    source: &Path,
    destination: &Path,
    durability: RecoveryCopyDurability,
) -> Result<(), RecoveryError> {
    let metadata = source.symlink_metadata()?;
    reject_recovery_link(&metadata)?;
    if metadata.is_dir() {
        std::fs::create_dir(destination)?;
        for entry in std::fs::read_dir(source)? {
            let entry = entry?;
            if is_apple_double(&entry.file_name()) {
                continue;
            }
            copy_recovery_input_with_durability(
                &entry.path(),
                &destination.join(entry.file_name()),
                durability,
            )?;
        }
    } else if metadata.is_file() {
        let mut input = std::fs::File::open(source)?;
        #[cfg(target_os = "macos")]
        if clone_recovery_file(&input, destination) {
            if durability == RecoveryCopyDurability::Durable {
                std::fs::File::open(destination)?.sync_all()?;
            }
            return Ok(());
        }
        let mut output = std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(destination)?;
        std::io::copy(&mut input, &mut output)?;
        if durability == RecoveryCopyDurability::Durable {
            output.sync_all()?;
        }
    } else {
        return Err(RecoveryError::Validation(format!(
            "Unsupported recovery input: {}",
            source.display()
        )));
    }
    Ok(())
}

#[cfg(target_os = "macos")]
fn clone_recovery_file(input: &std::fs::File, destination: &Path) -> bool {
    use std::{os::fd::AsRawFd, os::unix::ffi::OsStrExt};

    let Ok(destination) = std::ffi::CString::new(destination.as_os_str().as_bytes()) else {
        return false;
    };
    unsafe { libc::fclonefileat(input.as_raw_fd(), libc::AT_FDCWD, destination.as_ptr(), 0) == 0 }
}

type RecoverySnapshot = std::collections::BTreeMap<PathBuf, Option<Vec<u8>>>;

fn hash_recovery_file(root: &Path, path: &Path) -> Result<(PathBuf, Vec<u8>), RecoveryError> {
    use std::io::Read;

    let metadata = path.symlink_metadata()?;
    reject_recovery_link(&metadata)?;
    if !metadata.is_file() {
        return Err(RecoveryError::Validation(format!(
            "Unsupported recovery input: {}",
            path.display()
        )));
    }
    let mut input = std::fs::File::open(path)?;
    let mut digest = blake3::Hasher::new();
    let mut buffer = [0_u8; 65536];
    loop {
        let count = input.read(&mut buffer)?;
        if count == 0 {
            break;
        }
        digest.update(&buffer[..count]);
    }
    let relative = path
        .strip_prefix(root)
        .map_err(|error| RecoveryError::Validation(error.to_string()))?
        .to_path_buf();
    Ok((relative, digest.finalize().as_bytes().to_vec()))
}

fn hash_recovery_files(root: &Path, paths: &[PathBuf]) -> Result<RecoverySnapshot, RecoveryError> {
    let mut entries = RecoverySnapshot::new();
    for path in paths {
        let (relative, hash) = hash_recovery_file(root, path)?;
        let _ = entries.insert(relative, Some(hash));
    }
    Ok(entries)
}

const MAX_RECOVERY_HASH_WORKERS: usize = 8;

fn hash_recovery_files_parallel(
    root: &Path,
    paths: &[PathBuf],
    workers: usize,
) -> Result<RecoverySnapshot, RecoveryError> {
    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};

    let next = AtomicUsize::new(0);
    let failed = AtomicBool::new(false);
    let drain = || -> Result<Vec<(PathBuf, Vec<u8>)>, RecoveryError> {
        let mut hashes = Vec::new();
        while !failed.load(Ordering::Relaxed) {
            let Some(path) = paths.get(next.fetch_add(1, Ordering::Relaxed)) else {
                break;
            };
            match hash_recovery_file(root, path) {
                Ok(hash) => hashes.push(hash),
                Err(error) => {
                    failed.store(true, Ordering::Relaxed);
                    return Err(error);
                }
            }
        }
        Ok(hashes)
    };
    std::thread::scope(|scope| {
        let helpers: Vec<_> = (1..workers)
            .filter_map(|_| {
                std::thread::Builder::new()
                    .name("studio-integrity-check".into())
                    .spawn_scoped(scope, drain)
                    .ok()
            })
            .collect();
        let own = drain();
        let results: Vec<_> = std::iter::once(Ok(own))
            .chain(helpers.into_iter().map(|helper| {
                helper.join().map_err(|_| {
                    RecoveryError::Validation("Recovery integrity worker panicked".into())
                })
            }))
            .collect();
        let mut first_error = None;
        let mut entries = RecoverySnapshot::new();
        for hashes in results {
            match hashes? {
                Ok(hashes) => {
                    entries.extend(hashes.into_iter().map(|(path, hash)| (path, Some(hash))))
                }
                Err(error) => {
                    first_error.get_or_insert(error);
                }
            }
        }
        match first_error {
            Some(error) => Err(error),
            None => Ok(entries),
        }
    })
}

fn recovery_snapshot(project: &Path) -> Result<RecoverySnapshot, RecoveryError> {
    fn visit(
        root: &Path,
        path: &Path,
        entries: &mut RecoverySnapshot,
        files: &mut Vec<PathBuf>,
        bytes: &mut u64,
    ) -> Result<(), RecoveryError> {
        let metadata = path.symlink_metadata()?;
        reject_recovery_link(&metadata)?;
        let relative = path
            .strip_prefix(root)
            .map_err(|error| RecoveryError::Validation(error.to_string()))?
            .to_path_buf();
        if metadata.is_dir() {
            let _ = entries.insert(relative, None);
            for entry in std::fs::read_dir(path)? {
                let entry = entry?;
                if !is_apple_double(&entry.file_name()) {
                    visit(root, &entry.path(), entries, files, bytes)?;
                }
            }
        } else if metadata.is_file() {
            files.push(path.to_path_buf());
            *bytes = bytes.saturating_add(metadata.len());
        } else {
            return Err(RecoveryError::Validation(format!(
                "Unsupported recovery input: {}",
                path.display()
            )));
        }
        Ok(())
    }
    let mut entries = RecoverySnapshot::new();
    let mut files = Vec::new();
    let mut bytes = 0;
    for name in RECOVERY_INPUTS {
        let path = project.join(name);
        match path.symlink_metadata() {
            Ok(_) => visit(project, &path, &mut entries, &mut files, &mut bytes)?,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(error) => return Err(error.into()),
        }
    }
    let workers = std::thread::available_parallelism()
        .map_or(1, |count| count.get())
        .min(MAX_RECOVERY_HASH_WORKERS)
        .min(files.len());
    let hashes = if bytes >= 32 * 1024 * 1024 && workers > 1 {
        hash_recovery_files_parallel(project, &files, workers)?
    } else {
        hash_recovery_files(project, &files)?
    };
    entries.extend(hashes);
    Ok(entries)
}

fn sync_recovery_input(path: &Path) -> Result<(), RecoveryError> {
    if path.is_dir() {
        for entry in std::fs::read_dir(path)? {
            sync_recovery_input(&entry?.path())?;
        }
    } else {
        std::fs::OpenOptions::new()
            .read(true)
            .write(true)
            .open(path)?
            .sync_all()?;
    }
    Ok(())
}

const RECOVERY_PUBLICATION: &str = ".recovery-publication.json";
const RECOVERY_PUBLICATION_RECEIPT: &str = "publication-receipt.json";
const RECOVERY_PUBLICATION_MAX_BYTES: u64 = 8192;

#[derive(Clone, Copy)]
enum RecoveryPublicationStampVersion {
    V1,
    V2,
    /// Leaves `._` AppleDouble entries out of the segments stamp. Receipts
    /// written as V1/V2 keep hashing them, so publications those builds
    /// interrupted still reconcile.
    V3,
}

#[derive(serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct RecoveryPublication {
    version: u32,
    project: PathBuf,
    workspace: String,
    original: RecoveryPublicationState,
    staged: RecoveryPublicationState,
}

#[derive(serde::Serialize, serde::Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
struct RecoveryPublicationState {
    segments: Option<[u8; 32]>,
    meta: Option<[u8; 32]>,
    config: Option<[u8; 32]>,
}

fn open_recovery_publication_file(path: &Path) -> std::io::Result<std::fs::File> {
    let mut options = std::fs::OpenOptions::new();
    options.read(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.custom_flags(libc::O_NOFOLLOW | libc::O_CLOEXEC | libc::O_NONBLOCK);
    }
    #[cfg(windows)]
    {
        use std::os::windows::fs::OpenOptionsExt;
        options.custom_flags(0x0020_0000);
    }
    let file = options.open(path)?;
    let metadata = file.metadata()?;
    if !metadata.is_file() || reject_recovery_link(&metadata).is_err() {
        return Err(std::io::Error::other("Invalid recovery publication file"));
    }
    Ok(file)
}

fn recovery_publication_file_digest(path: &Path) -> Result<Option<[u8; 32]>, RecoveryError> {
    use sha2::Digest;
    use std::io::Read;
    let mut file = match open_recovery_publication_file(path) {
        Ok(file) => file,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(error) => return Err(error.into()),
    };
    let mut digest = sha2::Sha256::new();
    let mut buffer = [0_u8; 65536];
    loop {
        let count = file.read(&mut buffer)?;
        if count == 0 {
            break;
        }
        digest.update(&buffer[..count]);
    }
    Ok(Some(digest.finalize().into()))
}

fn recovery_publication_segments_stamp(
    path: &Path,
    version: RecoveryPublicationStampVersion,
) -> Result<Option<[u8; 32]>, RecoveryError> {
    // These stamps locate the interrupted rename; ordinary recovery still validates media content.
    use sha2::Digest;
    #[derive(serde::Serialize)]
    struct Entry {
        directory: bool,
        size: u64,
        modified: Duration,
        created: Option<Duration>,
        #[cfg(unix)]
        identity: (u64, u64),
    }
    fn visit(
        root: &Path,
        path: &Path,
        entries: &mut std::collections::BTreeMap<PathBuf, Entry>,
        version: RecoveryPublicationStampVersion,
    ) -> Result<(), RecoveryError> {
        let metadata = path.symlink_metadata()?;
        reject_recovery_link(&metadata)?;
        if !metadata.is_file() && !metadata.is_dir() {
            return Err(RecoveryError::Validation(
                "Invalid publication tree entry".into(),
            ));
        }
        #[cfg(unix)]
        use std::os::unix::fs::MetadataExt;
        let _ = entries.insert(
            path.strip_prefix(root)
                .map_err(|error| RecoveryError::Validation(error.to_string()))?
                .to_path_buf(),
            Entry {
                directory: metadata.is_dir(),
                // V1 persists allocation sizes; some filesystems change directory sizes on rename.
                size: if metadata.is_dir()
                    && matches!(
                        version,
                        RecoveryPublicationStampVersion::V2 | RecoveryPublicationStampVersion::V3
                    ) {
                    0
                } else {
                    metadata.len()
                },
                modified: metadata
                    .modified()?
                    .duration_since(std::time::UNIX_EPOCH)
                    .map_err(|error| RecoveryError::Validation(error.to_string()))?,
                created: metadata
                    .created()
                    .ok()
                    .and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok()),
                #[cfg(unix)]
                identity: (metadata.dev(), metadata.ino()),
            },
        );
        if metadata.is_dir() {
            for entry in std::fs::read_dir(path)? {
                let entry = entry?;
                if matches!(version, RecoveryPublicationStampVersion::V3)
                    && is_apple_double(&entry.file_name())
                {
                    continue;
                }
                visit(root, &entry.path(), entries, version)?;
            }
        }
        Ok(())
    }
    match path.symlink_metadata() {
        Ok(metadata) => {
            reject_recovery_link(&metadata)?;
            if !metadata.is_dir() {
                return Err(RecoveryError::Validation(
                    "Publication segments are not a directory".into(),
                ));
            }
        }
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(error) => return Err(error.into()),
    }
    let mut entries = std::collections::BTreeMap::new();
    visit(path, path, &mut entries, version)?;
    Ok(Some(
        sha2::Sha256::digest(serde_json::to_vec(&entries)?).into(),
    ))
}

fn recovery_publication_state(project: &Path) -> Result<RecoveryPublicationState, RecoveryError> {
    recovery_publication_state_for_version(project, RecoveryPublicationStampVersion::V3)
}

fn recovery_publication_state_for_version(
    project: &Path,
    version: RecoveryPublicationStampVersion,
) -> Result<RecoveryPublicationState, RecoveryError> {
    for path in [project.to_path_buf(), project.join("content")] {
        let metadata = path.symlink_metadata()?;
        reject_recovery_link(&metadata)?;
        if !metadata.is_dir() {
            return Err(RecoveryError::Validation(
                "Invalid publication directory".into(),
            ));
        }
    }
    Ok(RecoveryPublicationState {
        segments: recovery_publication_segments_stamp(&project.join("content/segments"), version)?,
        meta: recovery_publication_file_digest(&project.join("recording-meta.json"))?,
        config: recovery_publication_file_digest(&project.join("project-config.json"))?,
    })
}

fn recovery_publication_workspace(project: &Path, name: &str) -> Result<PathBuf, RecoveryError> {
    let id = name
        .strip_prefix(".recovery-")
        .and_then(|value| uuid::Uuid::parse_str(value).ok())
        .filter(|id| name == format!(".recovery-{id}"))
        .ok_or_else(|| {
            RecoveryError::Validation("Invalid publication workspace generation".into())
        })?;
    let workspace = project.join(format!(".recovery-{id}"));
    let metadata = workspace.symlink_metadata()?;
    reject_recovery_link(&metadata)?;
    if !metadata.is_dir() {
        return Err(RecoveryError::Validation(
            "Invalid publication workspace".into(),
        ));
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        if metadata.uid() != unsafe { libc::geteuid() } || metadata.mode() & 0o077 != 0 {
            return Err(RecoveryError::Validation(
                "Publication workspace is not privately owned".into(),
            ));
        }
    }
    Ok(workspace)
}

fn read_recovery_publication(path: &Path) -> std::io::Result<Vec<u8>> {
    use std::io::Read;
    let file = open_recovery_publication_file(path)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        let metadata = file.metadata()?;
        if metadata.nlink() != 1
            || metadata.uid() != unsafe { libc::geteuid() }
            || metadata.mode() & 0o077 != 0
        {
            return Err(std::io::Error::other(
                "Recovery publication receipt is not privately owned",
            ));
        }
    }
    let mut bytes = Vec::new();
    file.take(RECOVERY_PUBLICATION_MAX_BYTES + 1)
        .read_to_end(&mut bytes)?;
    if bytes.len() as u64 > RECOVERY_PUBLICATION_MAX_BYTES {
        return Err(std::io::Error::other(
            "Recovery publication receipt is too large",
        ));
    }
    Ok(bytes)
}

fn finish_recovery_publication(
    project: &Path,
    workspace: &Path,
    bytes: &[u8],
) -> Result<(), RecoveryError> {
    if read_recovery_publication(&project.join(RECOVERY_PUBLICATION))? != bytes
        || read_recovery_publication(&workspace.join(RECOVERY_PUBLICATION_RECEIPT))? != bytes
    {
        return Err(RecoveryError::Validation(
            "Publication receipt changed; evidence retained".into(),
        ));
    }
    std::fs::remove_file(project.join(RECOVERY_PUBLICATION))?;
    Ok(())
}

fn begin_recovery_publication(project: &Path, workspace: &Path) -> Result<Vec<u8>, RecoveryError> {
    use std::io::Write;
    let name = workspace
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| {
            RecoveryError::Validation("Missing publication workspace generation".into())
        })?;
    if workspace != recovery_publication_workspace(project, name)?.as_path() {
        return Err(RecoveryError::Validation(
            "Publication workspace is outside the project".into(),
        ));
    }
    let receipt = RecoveryPublication {
        version: 3,
        project: project.canonicalize()?,
        workspace: name.into(),
        original: recovery_publication_state(project)?,
        staged: recovery_publication_state(&workspace.join("staged"))?,
    };
    if receipt.original.segments.is_none()
        || receipt.original.meta.is_none()
        || receipt.staged.segments.is_none()
        || receipt.staged.meta.is_none()
        || receipt.staged.config.is_none()
    {
        return Err(RecoveryError::Validation(
            "Incomplete recovery publication".into(),
        ));
    }
    let bytes = serde_json::to_vec(&receipt)?;
    if bytes.len() as u64 > RECOVERY_PUBLICATION_MAX_BYTES {
        return Err(RecoveryError::Validation(
            "Recovery publication receipt is too large".into(),
        ));
    }
    for path in [
        workspace.join(RECOVERY_PUBLICATION_RECEIPT),
        project.join(RECOVERY_PUBLICATION),
    ] {
        let mut options = std::fs::OpenOptions::new();
        options.write(true).create_new(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            options
                .mode(0o600)
                .custom_flags(libc::O_NOFOLLOW | libc::O_CLOEXEC);
        }
        let mut file = options.open(path)?;
        file.write_all(&bytes)?;
        file.sync_all()?;
    }
    Ok(bytes)
}

fn reconcile_recovery_publication(project: &Path) -> Result<(), RecoveryError> {
    let bytes = match read_recovery_publication(&project.join(RECOVERY_PUBLICATION)) {
        Ok(bytes) => bytes,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            if !project.join("content/segments").try_exists()?
                && RecordingMeta::load_for_project(project)
                    .ok()
                    .is_some_and(|meta| meta.studio_meta().is_some())
            {
                for entry in std::fs::read_dir(project)? {
                    if entry?
                        .file_name()
                        .to_string_lossy()
                        .starts_with(".recovery-")
                    {
                        return Err(RecoveryError::Validation("Missing segments with an unbound recovery workspace; evidence retained".into()));
                    }
                }
            }
            return Ok(());
        }
        Err(error) => return Err(error.into()),
    };
    let receipt: RecoveryPublication = serde_json::from_slice(&bytes)?;
    let version = match receipt.version {
        1 => RecoveryPublicationStampVersion::V1,
        2 => RecoveryPublicationStampVersion::V2,
        3 => RecoveryPublicationStampVersion::V3,
        _ => {
            return Err(RecoveryError::Validation(
                "Invalid publication identity; evidence retained".into(),
            ));
        }
    };
    if receipt.project != project.canonicalize()?
        || receipt.original.meta.is_none()
        || receipt.original.segments.is_none()
        || receipt.staged.meta.is_none()
        || receipt.staged.segments.is_none()
        || receipt.staged.config.is_none()
    {
        return Err(RecoveryError::Validation(
            "Invalid publication identity; evidence retained".into(),
        ));
    }
    let workspace = recovery_publication_workspace(project, &receipt.workspace)?;
    if read_recovery_publication(&workspace.join(RECOVERY_PUBLICATION_RECEIPT))? != bytes {
        return Err(RecoveryError::Validation(
            "Publication generation does not match its workspace".into(),
        ));
    }
    let current = recovery_publication_state_for_version(project, version)?;
    let staged = recovery_publication_state_for_version(&workspace.join("staged"), version)?;
    let backup =
        recovery_publication_segments_stamp(&workspace.join("original-segments"), version)?;
    let backup_config =
        recovery_publication_file_digest(&workspace.join("original-project-config.json"))?;
    if recovery_publication_file_digest(&workspace.join("original-recording-meta.json"))?
        != receipt.original.meta
    {
        return Err(RecoveryError::Validation(
            "Original publication metadata changed".into(),
        ));
    }
    let config_rolled_back = current.meta == receipt.original.meta
        && current.config == receipt.original.config
        && staged.meta == receipt.staged.meta
        && staged.config.is_none()
        && backup_config.is_none();
    let before_move = (current == receipt.original
        && staged == receipt.staged
        && backup.is_none()
        && (backup_config == receipt.original.config || backup_config.is_none()))
        || (config_rolled_back
            && current == receipt.original
            && staged.segments == receipt.staged.segments
            && backup.is_none());
    let missing_segments = (current.segments.is_none()
        && current.meta == receipt.original.meta
        && current.config == receipt.original.config
        && staged == receipt.staged
        && backup == receipt.original.segments
        && backup_config == receipt.original.config)
        || (config_rolled_back
            && current.segments.is_none()
            && staged.segments == receipt.staged.segments
            && backup == receipt.original.segments);
    let installed_segments = (current.segments == receipt.staged.segments
        && current.meta == receipt.original.meta
        && backup == receipt.original.segments
        && backup_config == receipt.original.config
        && staged.segments.is_none()
        && staged.meta == receipt.staged.meta
        && ((current.config == receipt.original.config && staged.config == receipt.staged.config)
            || (current.config == receipt.staged.config && staged.config.is_none())))
        || (config_rolled_back
            && current.segments == receipt.staged.segments
            && staged.segments.is_none()
            && backup == receipt.original.segments);
    let committed = current == receipt.staged
        && backup == receipt.original.segments
        && backup_config == receipt.original.config
        && staged.segments.is_none()
        && staged.meta.is_none()
        && staged.config.is_none();
    if missing_segments {
        let destination = project.join("content/segments");
        match destination.symlink_metadata() {
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Ok(_) => {
                return Err(RecoveryError::Validation(
                    "Canonical segments appeared during reconciliation".into(),
                ));
            }
            Err(error) => return Err(error.into()),
        }
        std::fs::rename(workspace.join("original-segments"), destination)?;
        if recovery_publication_state_for_version(project, version)? != receipt.original {
            return Err(RecoveryError::Validation(
                "Restored publication state changed; evidence retained".into(),
            ));
        }
    } else if !before_move && !installed_segments && !committed {
        return Err(RecoveryError::Validation(
            "Conflicting recovery publication state; all files retained".into(),
        ));
    }
    finish_recovery_publication(project, &workspace, &bytes)
}

fn publish_recovery(project: &Path, workspace: &Path) -> Result<(), RecoveryError> {
    publish_recovery_with(project, workspace, rename_recovery_path)
}

fn publish_recovery_with_source(
    project: &Path,
    workspace: &Path,
    source: &RelocatableSource,
) -> Result<(), RecoveryError> {
    let original = project.join("content/segments");
    let backup = workspace.join("original-segments");
    publish_recovery_with(project, workspace, |from, to| {
        rename_recovery_path_with_source(from, to, &original, &backup, source)
    })
}

fn rename_recovery_path_with_source(
    from: &Path,
    to: &Path,
    original: &Path,
    backup: &Path,
    source: &RelocatableSource,
) -> std::io::Result<()> {
    if (from == original && to == backup) || (from == backup && to == original) {
        source.relocate_from(from, to.to_path_buf())
    } else {
        rename_recovery_path(from, to)
    }
}

fn rename_recovery_path(source: &Path, destination: &Path) -> std::io::Result<()> {
    std::fs::rename(source, destination)
}

fn publish_recovery_with(
    project: &Path,
    workspace: &Path,
    mut rename: impl FnMut(&Path, &Path) -> std::io::Result<()>,
) -> Result<(), RecoveryError> {
    let staged = workspace.join("staged");
    let original_segments = project.join("content/segments");
    let backup_segments = workspace.join("original-segments");
    let config = project.join("project-config.json");
    let backup_config = workspace.join("original-project-config.json");
    let had_config = config.try_exists()?;
    if had_config {
        copy_recovery_input(&config, &backup_config)?;
    }
    copy_recovery_input(
        &project.join("recording-meta.json"),
        &workspace.join("original-recording-meta.json"),
    )?;
    let publication = begin_recovery_publication(project, workspace)?;
    if let Err(error) = rename(&original_segments, &backup_segments) {
        finish_recovery_publication(project, workspace, &publication)?;
        return Err(error.into());
    }
    let mut segments_published = false;
    let mut config_published = false;
    let result = (|| {
        rename(&staged.join("content/segments"), &original_segments)?;
        segments_published = true;
        rename(&staged.join("project-config.json"), &config)?;
        config_published = true;
        rename(
            &staged.join("recording-meta.json"),
            &project.join("recording-meta.json"),
        )?;
        Ok::<_, std::io::Error>(())
    })();
    if let Err(error) = result {
        let rollback = (|| {
            if config_published {
                if had_config {
                    rename(&backup_config, &config)?;
                } else {
                    std::fs::remove_file(&config)?;
                }
            }
            if segments_published {
                rename(&original_segments, &staged.join("content/segments"))?;
            }
            rename(&backup_segments, &original_segments)?;
            Ok::<_, std::io::Error>(())
        })();
        if let Err(rollback_error) = rollback {
            return Err(RecoveryError::Validation(format!(
                "Publication failed: {error}; rollback failed: {rollback_error}; original media and metadata retained at {}",
                workspace.display()
            )));
        }
        finish_recovery_publication(project, workspace, &publication)?;
        return Err(error.into());
    }
    finish_recovery_publication(project, workspace, &publication)?;
    Ok(())
}

fn finalized_audio_name(segment_dir: &Path, stem: &str, fragments: &[PathBuf]) -> String {
    let m4a = format!("{stem}.m4a");
    if let [source] = fragments
        && source
            .extension()
            .is_some_and(|extension| extension.eq_ignore_ascii_case("m4a"))
    {
        let output = segment_dir.join(&m4a);
        let source = if source.is_file() {
            source.as_path()
        } else {
            output.as_path()
        };
        if ffmpeg::format::input(source).is_ok_and(|input| {
            input.streams().best(ffmpeg::media::Type::Video).is_none()
                && input
                    .streams()
                    .best(ffmpeg::media::Type::Audio)
                    .is_some_and(|stream| stream.parameters().id() == ffmpeg::codec::Id::AAC)
        }) {
            return m4a;
        }
    }
    format!("{stem}.ogg")
}

fn finalize_m4a(source: &Path, output: &Path) -> Result<(), RecoveryError> {
    let temporary = output.with_extension(format!("{}.m4a", uuid::Uuid::new_v4()));
    remux_file(source, &temporary).map_err(RecoveryError::AudioConcat)?;
    replace_file(&temporary, output)?;
    if source != output {
        std::fs::remove_file(source)?;
    }
    Ok(())
}

fn validate_recovered_track(path: &Path, kind: ffmpeg::media::Type) -> Result<(), RecoveryError> {
    validate_recovery_track(path, kind, VideoValidation::Full)
}

const MAX_AUDIO_VALIDATION_WORKERS: usize = 4;

const AUDIO_FINALIZE_STACK_SIZE: usize = 16 * 1024 * 1024;

fn validate_recovered_audio_in_order(paths: &[&PathBuf]) -> Result<(), RecoveryError> {
    use std::sync::atomic::{AtomicUsize, Ordering};

    let workers = std::thread::available_parallelism()
        .map_or(1, |count| count.get())
        .min(MAX_AUDIO_VALIDATION_WORKERS)
        .min(paths.len());
    if workers <= 1 {
        for path in paths {
            validate_recovered_track(path, ffmpeg::media::Type::Audio)?;
        }
        return Ok(());
    }
    let next = AtomicUsize::new(0);
    let drain = || {
        let mut results = Vec::new();
        loop {
            let index = next.fetch_add(1, Ordering::Relaxed);
            let Some(path) = paths.get(index) else {
                break;
            };
            results.push((
                index,
                validate_recovered_track(path, ffmpeg::media::Type::Audio),
            ));
        }
        results
    };
    let mut results = std::thread::scope(|scope| {
        let helpers = (1..workers)
            .filter_map(|_| {
                std::thread::Builder::new()
                    .name("studio-audio-validate".into())
                    .stack_size(AUDIO_FINALIZE_STACK_SIZE)
                    .spawn_scoped(scope, drain)
                    .ok()
            })
            .collect::<Vec<_>>();
        let mut results = drain();
        for helper in helpers {
            match helper.join() {
                Ok(helper_results) => results.extend(helper_results),
                Err(_) => {
                    return Err(RecoveryError::Validation(
                        "Studio audio validation panicked".into(),
                    ));
                }
            }
        }
        Ok(results)
    })?;
    results.sort_by_key(|(index, _)| *index);
    results.into_iter().try_for_each(|(_, result)| result)
}

fn full_validation_decode_threads() -> usize {
    std::thread::available_parallelism().map_or(1, |count| count.get().min(8))
}

fn validate_recovery_track(
    path: &Path,
    kind: ffmpeg::media::Type,
    video_validation: VideoValidation,
) -> Result<(), RecoveryError> {
    let validate = || -> Result<(), String> {
        let mut input = ffmpeg::format::input(path).map_err(|error| error.to_string())?;
        let stream = input
            .streams()
            .best(kind)
            .ok_or_else(|| format!("Missing {kind:?} stream"))?;
        let index = stream.index();
        let mut context = ffmpeg::codec::Context::from_parameters(stream.parameters())
            .map_err(|error| error.to_string())?;
        if kind == ffmpeg::media::Type::Video && video_validation == VideoValidation::Full {
            context.set_threading(ffmpeg::threading::Config {
                kind: ffmpeg::threading::Type::Frame,
                count: full_validation_decode_threads(),
            });
        }
        let codec =
            ffmpeg::decoder::find(context.id()).ok_or_else(|| "Decoder unavailable".to_string())?;
        let mut decoder = context.decoder();
        decoder.check(ffmpeg::codec::decoder::Check::EXPLODE | ffmpeg::codec::decoder::Check::CRC);
        let mut decoder = decoder.open_as(codec).map_err(|error| error.to_string())?;
        let mut frame = unsafe { ffmpeg::Frame::empty() };
        let mut decoded = false;
        loop {
            let mut packet = ffmpeg::Packet::empty();
            match packet.read(&mut input) {
                Ok(()) => {}
                Err(ffmpeg::Error::Eof) => break,
                Err(error) => return Err(error.to_string()),
            }
            if packet.stream() != index {
                continue;
            }
            if packet.is_corrupt() {
                return Err("Corrupt packet".into());
            }
            if decoded
                && kind == ffmpeg::media::Type::Video
                && video_validation == VideoValidation::Bounded
            {
                continue;
            }
            decoder
                .send_packet(&packet)
                .map_err(|error| error.to_string())?;
            loop {
                match decoder.receive_frame(&mut frame) {
                    Ok(()) if !frame.is_corrupt() => decoded = true,
                    Ok(()) => return Err("Corrupt decoded frame".into()),
                    Err(ffmpeg::Error::Other { errno }) if errno == ffmpeg::ffi::EAGAIN => break,
                    Err(error) => return Err(error.to_string()),
                }
            }
        }
        decoder.send_eof().map_err(|error| error.to_string())?;
        loop {
            match decoder.receive_frame(&mut frame) {
                Ok(()) if !frame.is_corrupt() => decoded = true,
                Ok(()) => return Err("Corrupt decoded frame".into()),
                Err(ffmpeg::Error::Eof) => break,
                Err(error) => return Err(error.to_string()),
            }
        }
        if !decoded {
            return Err("Track contains no decoded frames".into());
        }
        Ok(())
    };
    validate().map_err(|error| RecoveryError::Validation(format!("{}: {error}", path.display())))
}

fn start_time_or_display_fallback(
    original_time: Option<f64>,
    display_start_time: Option<f64>,
) -> Option<f64> {
    original_time.or(display_start_time)
}

#[cfg(test)]
fn valid_recovered_audio(path: &Path) -> bool {
    path.is_file() && validate_recovered_track(path, ffmpeg::media::Type::Audio).is_ok()
}

fn replace_file(src: &Path, dst: &Path) -> Result<(), RecoveryError> {
    if dst.exists() {
        std::fs::remove_file(dst).map_err(RecoveryError::Io)?;
    }

    std::fs::rename(src, dst).map_err(RecoveryError::Io)
}

#[cfg(test)]
mod instant_cleanup_tests {
    use super::*;
    use cap_enc_ffmpeg::segmented_stream::{SegmentedVideoEncoder, SegmentedVideoEncoderConfig};
    use std::{cell::Cell, fs, io};

    fn playable_instant_project() -> tempfile::TempDir {
        ffmpeg::init().unwrap();
        let directory = tempfile::tempdir().unwrap();
        let display = directory.path().join("content/display");
        let mut encoder = SegmentedVideoEncoder::init(
            display,
            cap_media_info::VideoInfo {
                pixel_format: cap_media_info::Pixel::NV12,
                width: 320,
                height: 240,
                time_base: ffmpeg::Rational(1, 1_000_000),
                frame_rate: ffmpeg::Rational(30, 1),
            },
            SegmentedVideoEncoderConfig {
                segment_duration: Duration::from_secs(1),
                ..Default::default()
            },
        )
        .unwrap();
        for index in 0..60 {
            let mut frame = ffmpeg::frame::Video::new(ffmpeg::format::Pixel::NV12, 320, 240);
            frame.data_mut(0).fill(32 + index as u8);
            frame.data_mut(1).fill(128);
            encoder
                .queue_frame(frame, Duration::from_micros(index * 1_000_000 / 30))
                .unwrap();
        }
        encoder.finish().unwrap();
        assert!(!encoder.completed_segments().is_empty());
        drop(encoder);
        directory
    }

    fn refuse_workspace_cleanup(workspace: &Path) -> io::Result<()> {
        assert!(workspace.is_dir());
        Err(io::Error::new(
            io::ErrorKind::PermissionDenied,
            "injected workspace cleanup failure",
        ))
    }

    #[test]
    fn existing_instant_validation_is_read_only_and_requires_requested_audio() {
        let directory = playable_instant_project();
        let project = directory.path();
        let output = project.join("content/output.mp4");
        RecoveryManager::finalize_instant_output(
            &project.join("content/display"),
            &project.join("content/audio"),
            &output,
        )
        .unwrap();
        let before = recovery_snapshot(project).unwrap();
        assert_eq!(
            RecoveryManager::validate_instant_output(project, false).unwrap(),
            output
        );
        assert!(RecoveryManager::validate_instant_output(project, true).is_err());
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        fs::write(&output, b"invalid media retained for repair").unwrap();
        let before = recovery_snapshot(project).unwrap();
        assert!(RecoveryManager::validate_instant_output(project, false).is_err());
        assert_eq!(recovery_snapshot(project).unwrap(), before);
    }

    fn retained_workspace(project: &Path) -> PathBuf {
        let workspaces: Vec<_> = fs::read_dir(project)
            .unwrap()
            .map(|entry| entry.unwrap().path())
            .filter(|path| {
                path.is_dir()
                    && path
                        .file_name()
                        .unwrap()
                        .to_string_lossy()
                        .starts_with(".recovery-")
            })
            .collect();
        assert_eq!(workspaces.len(), 1);
        workspaces.into_iter().next().unwrap()
    }

    #[test]
    fn cleanup_failure_does_not_fail_published_instant_output() {
        for completed in [false, true] {
            let directory = playable_instant_project();
            let project = directory.path();
            let output = project.join("content/output.mp4");
            let before = recovery_snapshot(project).unwrap();
            let cleanup_attempted = Cell::new(false);
            let result = RecoveryManager::finalize_instant_output_with(
                &project.join("content/display"),
                &project.join("content/audio"),
                &output,
                completed.then(|| (project.to_path_buf(), false)),
                |source, destination| fs::rename(source, destination),
                |workspace| {
                    cleanup_attempted.set(true);
                    refuse_workspace_cleanup(workspace)
                },
            )
            .unwrap();

            assert_eq!(result, output);
            assert!(cleanup_attempted.get());
            validate_recovered_track(&output, ffmpeg::media::Type::Video).unwrap();
            assert!(
                !retained_workspace(project)
                    .join("content/output.mp4")
                    .exists()
            );
            let mut after = recovery_snapshot(project).unwrap();
            assert!(after.remove(Path::new("content/output.mp4")).is_some());
            assert_eq!(after, before);
        }
    }

    #[test]
    fn cleanup_failure_preserves_instant_validation_error() {
        for completed in [false, true] {
            let directory = playable_instant_project();
            let project = directory.path();
            let audio = project.join("content/audio");
            fs::create_dir(&audio).unwrap();
            let before = recovery_snapshot(project).unwrap();
            let output = project.join("content/output.mp4");
            let cleanup_attempted = Cell::new(false);
            let error = RecoveryManager::finalize_instant_output_with(
                &project.join("content/display"),
                &audio,
                &output,
                completed.then(|| (project.to_path_buf(), true)),
                |_, _| panic!("invalid recording must not reach publication"),
                |workspace| {
                    cleanup_attempted.set(true);
                    refuse_workspace_cleanup(workspace)
                },
            )
            .unwrap_err();

            assert!(cleanup_attempted.get());
            assert!(matches!(error, RecoveryError::Validation(message)
                if message == "Required Instant audio has no recoverable fragments"));
            assert!(!output.exists());
            assert!(retained_workspace(project).is_dir());
            assert_eq!(recovery_snapshot(project).unwrap(), before);
        }
    }

    #[test]
    fn cleanup_failure_preserves_instant_publication_error() {
        for completed in [false, true] {
            let directory = playable_instant_project();
            let project = directory.path();
            let output = project.join("content/output.mp4");
            let before = recovery_snapshot(project).unwrap();
            let publication_attempted = Cell::new(false);
            let cleanup_attempted = Cell::new(false);
            let error = RecoveryManager::finalize_instant_output_with(
                &project.join("content/display"),
                &project.join("content/audio"),
                &output,
                completed.then(|| (project.to_path_buf(), false)),
                |source, destination| {
                    assert_eq!(destination, output);
                    validate_recovered_track(source, ffmpeg::media::Type::Video).unwrap();
                    publication_attempted.set(true);
                    Err(io::Error::new(
                        io::ErrorKind::PermissionDenied,
                        "injected publication failure",
                    ))
                },
                |workspace| {
                    cleanup_attempted.set(true);
                    refuse_workspace_cleanup(workspace)
                },
            )
            .unwrap_err();

            assert!(publication_attempted.get());
            assert!(cleanup_attempted.get());
            assert!(matches!(error, RecoveryError::Io(error)
                if error.kind() == io::ErrorKind::PermissionDenied
                    && error.to_string() == "injected publication failure"));
            assert!(!output.exists());
            assert!(
                retained_workspace(project)
                    .join("content/output.mp4")
                    .is_file()
            );
            assert_eq!(recovery_snapshot(project).unwrap(), before);
        }
    }
}

#[cfg(test)]
mod clean_studio_snapshot_tests {
    use super::*;
    use cap_enc_ffmpeg::segmented_stream::{SegmentedVideoEncoder, SegmentedVideoEncoderConfig};
    use std::{cell::Cell, cell::RefCell, fs, io};

    fn wait_for_recovery_lock(project: &Path) -> RecoveryLock {
        let started = Instant::now();
        loop {
            match RecoveryLock::acquire(project) {
                Ok(lock) => return lock,
                Err(error) => {
                    assert!(started.elapsed() < Duration::from_secs(5), "{error}");
                    std::thread::sleep(Duration::from_millis(5));
                }
            }
        }
    }

    const DISPLAY: &str = "content/segments/segment-0/display";
    const FRAGMENT: &str = "content/segments/segment-0/display/segment_001.m4s";
    const OUTPUT: &str = "content/segments/segment-0/display.mp4";

    fn playable_studio_project(status: StudioRecordingStatus) -> tempfile::TempDir {
        studio_project_with_frames(status, 30, (0..60).map(|index| index * 1_000_000 / 30))
    }

    fn studio_project_with_frames(
        status: StudioRecordingStatus,
        frame_rate: u32,
        frame_times_us: impl IntoIterator<Item = u64>,
    ) -> tempfile::TempDir {
        ffmpeg::init().unwrap();
        let directory = tempfile::tempdir().unwrap();
        let project = directory.path();
        let mut encoder = SegmentedVideoEncoder::init(
            project.join(DISPLAY),
            cap_media_info::VideoInfo {
                pixel_format: cap_media_info::Pixel::NV12,
                width: 320,
                height: 240,
                time_base: ffmpeg::Rational(1, 1_000_000),
                frame_rate: ffmpeg::Rational(frame_rate as i32, 1),
            },
            SegmentedVideoEncoderConfig {
                segment_duration: Duration::from_secs(1),
                ..Default::default()
            },
        )
        .unwrap();
        for (index, time_us) in frame_times_us.into_iter().enumerate() {
            let mut frame = ffmpeg::frame::Video::new(ffmpeg::format::Pixel::NV12, 320, 240);
            frame.data_mut(0).fill(32 + index as u8);
            frame.data_mut(1).fill(128);
            encoder
                .queue_frame(frame, Duration::from_micros(time_us))
                .unwrap();
        }
        encoder.finish().unwrap();
        drop(encoder);
        assert!(project.join(FRAGMENT).is_file());
        RecordingMeta {
            platform: None,
            project_path: project.to_path_buf(),
            pretty_name: "Snapshot finalization fixture".into(),
            sharing: None,
            upload: None,
            inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
                inner: MultipleSegments {
                    segments: vec![MultipleSegment {
                        display: VideoMeta {
                            path: OUTPUT.into(),
                            fps: frame_rate,
                            start_time: None,
                            device_id: None,
                        },
                        camera: None,
                        mic: None,
                        system_audio: None,
                        cursor: None,
                        keyboard: None,
                        display_notch: None,
                    }],
                    cursors: Cursors::default(),
                    status: Some(status),
                },
            })),
        }
        .save_for_project()
        .unwrap();
        ProjectConfiguration::default().write(project).unwrap();
        fs::write(
            project.join("recording-diagnostics.json"),
            br#"{"version":2,"segments":[{"trackFailures":[]}]}"#,
        )
        .unwrap();
        directory
    }

    fn add_fragmented_audio(project: &Path, name: &str, blocks: i64) -> PathBuf {
        use cap_enc_ffmpeg::fragmented_audio::FragmentedAudioFile;
        use ffmpeg::{ChannelLayout, format::Sample, format::sample::Type};

        let path = project.join(format!("content/segments/segment-0/{name}.m4a"));
        let mut encoder = FragmentedAudioFile::init(
            path.clone(),
            cap_media_info::AudioInfo::new_raw(Sample::F32(Type::Packed), 48_000, 1),
        )
        .unwrap();
        for block in 0..blocks {
            let mut frame =
                ffmpeg::frame::Audio::new(Sample::F32(Type::Packed), 1024, ChannelLayout::MONO);
            frame.set_rate(48_000);
            frame.set_pts(Some(block * 1024));
            for (index, value) in frame.data_mut(0)[..4096].chunks_exact_mut(4).enumerate() {
                let position = (block * 1024) as f32 + index as f32;
                let sample = (position * std::f32::consts::TAU * 440.0 / 48_000.0).sin() * 0.25;
                value.copy_from_slice(&sample.to_ne_bytes());
            }
            encoder
                .queue_frame(
                    frame,
                    Duration::from_secs_f64(block as f64 * 1024.0 / 48_000.0),
                )
                .unwrap();
        }
        encoder.finish().unwrap().unwrap();
        path
    }

    fn respawn_only_studio_project() -> tempfile::TempDir {
        let directory = playable_studio_project(StudioRecordingStatus::InProgress);
        let project = directory.path();
        let display = project.join(DISPLAY);
        RecoveryManager::finalize_to_progressive_mp4(
            &display,
            &project.join("content/segments/segment-0/camera.mp4"),
        )
        .unwrap();
        let init = fs::read(display.join("init.mp4")).unwrap();
        let fragment = fs::read(project.join(FRAGMENT)).unwrap();
        let successful = project.join("successful-muxer");
        fs::rename(&display, &successful).unwrap();
        fs::create_dir(&display).unwrap();
        fs::write(display.join("init.mp4"), init).unwrap();
        fs::write(display.join("segment_001.m4s.tmp"), &fragment[..24]).unwrap();
        fs::write(
            display.join("manifest.json"),
            br#"{"version":5,"type":"m4s_segments","init_segment":"init.mp4","segments":[{"path":"segment_001.m4s","is_complete":false}]}"#,
        )
        .unwrap();
        fs::rename(successful, display.join("respawn-1")).unwrap();
        add_fragmented_audio(project, "audio-input", 94);
        directory
    }

    #[test]
    fn respawn_only_studio_recovery_preserves_video_camera_and_audio() {
        let directory = respawn_only_studio_project();
        let project = directory.path();
        let camera = project.join("content/segments/segment-0/camera.mp4");
        let packets = |path: &Path| {
            ffmpeg::format::input(path)
                .unwrap()
                .packets()
                .map(|(_, packet)| packet.data().unwrap().to_vec())
                .collect::<Vec<_>>()
        };
        let expected = packets(&camera);
        assert_eq!(expected.len(), 60);
        let audio = project.join("content/segments/segment-0/audio-input.m4a");
        let expected_audio = packets(&audio);
        assert!(!expected_audio.is_empty());
        let before = recovery_snapshot(project).unwrap();
        let recording = RecoveryManager::inspect_recording(project)
            .expect("Completed respawn footage must be offered for recovery");
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        let recovered = RecoveryManager::recover(&recording).unwrap();
        assert_eq!(packets(&project.join(OUTPUT)), expected);
        assert_eq!(packets(&camera), expected);
        assert_eq!(packets(&audio), expected_audio);
        assert!(valid_recovered_audio(&audio));
        assert!(matches!(
            recovered.meta.status(),
            StudioRecordingStatus::Complete
        ));
        let StudioRecordingMeta::MultipleSegments { inner } = recovered.meta else {
            panic!("Expected segmented Studio metadata");
        };
        assert!(inner.segments[0].camera.is_some());
        assert!(inner.segments[0].mic.is_some());
        ProjectConfiguration::load(project)
            .unwrap()
            .validate()
            .unwrap();
    }

    #[test]
    fn respawn_only_video_finalization_keeps_every_complete_packet() {
        let directory = respawn_only_studio_project();
        let project = directory.path();
        copy_recovery_input(
            &project.join(format!("{DISPLAY}/respawn-1")),
            &project.join(format!("{DISPLAY}/respawn-2")),
        )
        .unwrap();
        RecoveryManager::finalize_to_progressive_mp4(&project.join(DISPLAY), &project.join(OUTPUT))
            .expect("Completed respawn fragments must not require an initial complete fragment");
        validate_recovered_track(&project.join(OUTPUT), ffmpeg::media::Type::Video).unwrap();
        let packets = ffmpeg::format::input(&project.join(OUTPUT))
            .unwrap()
            .packets()
            .count();
        assert_eq!(packets, 120);
    }

    #[test]
    fn respawn_only_studio_recovery_salvages_complete_prefix_from_pending_tail() {
        let directory = respawn_only_studio_project();
        let project = directory.path();
        let fragment = project.join(format!("{DISPLAY}/respawn-1/segment_001.m4s"));
        let mut bytes = fs::read(&fragment).unwrap();
        bytes.extend_from_slice(b"\0\0\0\x20moof\0\0");
        fs::write(fragment.with_extension("m4s.tmp"), bytes).unwrap();
        fs::remove_file(fragment).unwrap();
        let manifest = project.join(format!("{DISPLAY}/respawn-1/manifest.json"));
        let mut value: serde_json::Value =
            serde_json::from_slice(&fs::read(&manifest).unwrap()).unwrap();
        value["segments"][0]["is_complete"] = false.into();
        fs::write(manifest, serde_json::to_vec(&value).unwrap()).unwrap();
        let before = recovery_snapshot(project).unwrap();
        let recording = RecoveryManager::inspect_recording(project).unwrap();
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        RecoveryManager::recover(&recording).unwrap();
        validate_recovered_track(&project.join(OUTPUT), ffmpeg::media::Type::Video).unwrap();
        assert_eq!(
            ffmpeg::format::input(&project.join(OUTPUT))
                .unwrap()
                .packets()
                .count(),
            60
        );
    }

    #[test]
    fn corrupt_respawn_recovery_preserves_original_tracks() {
        let directory = respawn_only_studio_project();
        let project = directory.path();
        fs::write(
            project.join(format!("{DISPLAY}/respawn-1/init.mp4")),
            b"corrupt init",
        )
        .unwrap();
        let before = recovery_snapshot(project).unwrap();
        let recording = RecoveryManager::inspect_recording(project)
            .expect("Respawn fragments must be inspected before full validation");
        assert!(RecoveryManager::recover(&recording).is_err());
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        assert!(!project.join(OUTPUT).exists());
    }

    #[test]
    fn empty_orphan_segment_directory_recovers_every_real_frame() {
        let directory = playable_studio_project(StudioRecordingStatus::InProgress);
        let project = directory.path();
        fs::create_dir_all(project.join("content/segments/segment-1")).unwrap();
        let recording = RecoveryManager::inspect_recording(project).unwrap();
        assert_eq!(recording.recoverable_segments.len(), 1);
        let recovered = RecoveryManager::recover(&recording).unwrap();
        validate_recovered_track(&project.join(OUTPUT), ffmpeg::media::Type::Video).unwrap();
        assert_eq!(
            ffmpeg::format::input(&project.join(OUTPUT))
                .unwrap()
                .packets()
                .count(),
            60
        );
        let StudioRecordingMeta::MultipleSegments { inner } = recovered.meta else {
            panic!("Expected segmented Studio metadata");
        };
        assert_eq!(inner.segments.len(), 1);
    }

    fn completed_preparing_fixture(project: &Path) -> CompletedRecording {
        use crate::studio_recording::CleanStoppedStudio;

        let mut metadata = RecordingMeta::load_for_project(project).unwrap();
        let RecordingMetaInner::Studio(studio) = &mut metadata.inner else {
            panic!()
        };
        let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
            panic!()
        };
        inner.segments[0].display.path = DISPLAY.into();
        inner.segments[0].display.start_time = Some(0.0);
        let configuration = ProjectConfiguration {
            timeline: Some(
                serde_json::from_value(serde_json::json!({
                    "segments": [{"recordingSegment": 0, "timescale": 1.0, "start": 0.0, "end": 2.0}],
                    "zoomSegments": []
                }))
                .unwrap(),
            ),
            ..ProjectConfiguration::default()
        };
        metadata.save_for_project().unwrap();
        configuration.write(project).unwrap();
        CompletedRecording {
            project_path: project.to_path_buf(),
            meta: metadata.studio_meta().unwrap().clone(),
            cursor_data: Default::default(),
            clean_stopped: CleanStoppedStudio::for_test(metadata, configuration),
        }
    }

    enum PreparingEntryCase {
        Supported,
        EditedConfiguration,
        EditedMetadata,
        WrongStoppedProject,
        StaleAnalysis,
        RequiredTrackFailure,
        HeldRecoveryLock,
    }

    fn assert_preparing_entry_point_matches_ordinary(case: PreparingEntryCase) {
        use super::preparing_observer::PreparingStudioTestTransition;

        let candidate = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let completed = completed_preparing_fixture(candidate.path());
        let ordinary = tempfile::tempdir().unwrap();
        for entry in fs::read_dir(candidate.path()).unwrap() {
            let entry = entry.unwrap();
            copy_recovery_input(&entry.path(), &ordinary.path().join(entry.file_name())).unwrap();
        }
        assert_eq!(
            recovery_snapshot(candidate.path()).unwrap(),
            recovery_snapshot(ordinary.path()).unwrap()
        );
        let mut candidate_recording = RecoveryManager::inspect_recording(candidate.path()).unwrap();
        let mut ordinary_recording = RecoveryManager::inspect_recording(ordinary.path()).unwrap();
        let alternate = tempfile::tempdir().unwrap();
        let (job, observer) = if matches!(case, PreparingEntryCase::WrongStoppedProject) {
            let mut metadata = RecordingMeta::load_for_project(candidate.path()).unwrap();
            metadata.project_path = alternate.path().to_path_buf();
            let configuration = ProjectConfiguration::load(candidate.path()).unwrap();
            let alternate_completed = CompletedRecording {
                project_path: alternate.path().to_path_buf(),
                meta: metadata.studio_meta().unwrap().clone(),
                cursor_data: Default::default(),
                clean_stopped: crate::studio_recording::CleanStoppedStudio::for_test(
                    metadata,
                    configuration,
                ),
            };
            PreparingStudioJob::claim(&alternate_completed, 73).unwrap()
        } else {
            PreparingStudioJob::claim(&completed, 72).unwrap()
        };
        match case {
            PreparingEntryCase::Supported
            | PreparingEntryCase::WrongStoppedProject
            | PreparingEntryCase::HeldRecoveryLock => {}
            PreparingEntryCase::EditedConfiguration => {
                for path in [candidate.path(), ordinary.path()] {
                    let mut configuration = ProjectConfiguration::load(path).unwrap();
                    configuration.timeline.as_mut().unwrap().segments[0].name =
                        Some("Edited after Stop".into());
                    configuration.write(path).unwrap();
                }
            }
            PreparingEntryCase::EditedMetadata => {
                for path in [candidate.path(), ordinary.path()] {
                    let mut metadata = RecordingMeta::load_for_project(path).unwrap();
                    metadata.pretty_name.push_str(" edited after Stop");
                    metadata.save_for_project().unwrap();
                }
                candidate_recording = RecoveryManager::inspect_recording(candidate.path()).unwrap();
                ordinary_recording = RecoveryManager::inspect_recording(ordinary.path()).unwrap();
            }
            PreparingEntryCase::StaleAnalysis => {
                candidate_recording.meta.pretty_name.push_str(" stale");
                ordinary_recording.meta.pretty_name.push_str(" stale");
            }
            PreparingEntryCase::RequiredTrackFailure => {
                for path in [candidate.path(), ordinary.path()] {
                    fs::write(
                        path.join("recording-diagnostics.json"),
                        br#"{"version":2,"segments":[{"trackFailures":[{"track":"display","reason":"injected requested track failure"}]}]}"#,
                    )
                    .unwrap();
                }
            }
        }
        let candidate_before = recovery_snapshot(candidate.path()).unwrap();
        let ordinary_before = recovery_snapshot(ordinary.path()).unwrap();
        let transitions = job.test_transitions();
        let held_locks = matches!(case, PreparingEntryCase::HeldRecoveryLock).then(|| {
            (
                RecoveryLock::acquire(candidate.path()).unwrap(),
                RecoveryLock::acquire(ordinary.path()).unwrap(),
            )
        });
        let expected = RecoveryManager::finalize(&ordinary_recording)
            .map(|recording| serde_json::to_value(recording.meta).unwrap())
            .map_err(|error| error.to_string());
        let actual = RecoveryManager::finalize_with_preparing(&candidate_recording, job)
            .map(|recording| serde_json::to_value(recording.meta).unwrap())
            .map_err(|error| error.to_string());
        assert_eq!(actual, expected);
        assert_eq!(
            observer.publication_succeeded(),
            matches!(case, PreparingEntryCase::Supported) && actual.is_ok()
        );
        assert!(matches!(observer.latest(), PreparingStudioState::Ended));
        let expected_transitions = match case {
            PreparingEntryCase::Supported => vec![
                PreparingStudioTestTransition::Available,
                PreparingStudioTestTransition::Ended,
            ],
            PreparingEntryCase::EditedConfiguration => vec![
                PreparingStudioTestTransition::Unavailable(
                    "Persisted stopped configuration changed".into(),
                ),
                PreparingStudioTestTransition::Ended,
            ],
            PreparingEntryCase::EditedMetadata | PreparingEntryCase::WrongStoppedProject => vec![
                PreparingStudioTestTransition::Unavailable(
                    "Stopped recording identity or metadata changed".into(),
                ),
                PreparingStudioTestTransition::Ended,
            ],
            PreparingEntryCase::StaleAnalysis
            | PreparingEntryCase::RequiredTrackFailure
            | PreparingEntryCase::HeldRecoveryLock => vec![PreparingStudioTestTransition::Ended],
        };
        assert_eq!(*transitions.lock().unwrap(), expected_transitions);
        drop(held_locks);
        drop(wait_for_recovery_lock(candidate.path()));
        assert!(RecoveryLock::acquire(ordinary.path()).is_ok());
        if matches!(
            case,
            PreparingEntryCase::StaleAnalysis
                | PreparingEntryCase::RequiredTrackFailure
                | PreparingEntryCase::HeldRecoveryLock
        ) {
            assert!(actual.is_err());
            assert_eq!(
                recovery_snapshot(candidate.path()).unwrap(),
                candidate_before
            );
            assert_eq!(recovery_snapshot(ordinary.path()).unwrap(), ordinary_before);
            assert!(!candidate.path().join(OUTPUT).exists());
            assert!(!ordinary.path().join(OUTPUT).exists());
        } else {
            assert!(actual.is_ok());
            assert_eq!(
                recovery_snapshot(candidate.path()).unwrap(),
                recovery_snapshot(ordinary.path()).unwrap()
            );
            assert_eq!(
                fs::read(candidate.path().join(OUTPUT)).unwrap(),
                fs::read(ordinary.path().join(OUTPUT)).unwrap()
            );
            assert!(probe_video_can_decode(&candidate.path().join(OUTPUT)).unwrap());
        }
    }

    #[test]
    fn inspected_preparing_finalization_matches_ordinary_outputs_and_metadata() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::Supported);
    }

    #[test]
    fn preparing_retirement_preserves_every_encoded_video_packet() {
        fn packets(path: &Path) -> Vec<Vec<u8>> {
            let mut input = ffmpeg::format::input(path).unwrap();
            let video = input
                .streams()
                .best(ffmpeg::media::Type::Video)
                .unwrap()
                .index();
            input
                .packets()
                .filter_map(|(stream, packet)| {
                    (stream.index() == video).then(|| packet.data().unwrap().to_vec())
                })
                .collect()
        }

        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let completed = completed_preparing_fixture(project);
        let (job, observer) = PreparingStudioJob::claim(&completed, 42).unwrap();
        let metadata = RecordingMeta::load_for_project(project).unwrap();
        let recording = RecoveryManager::analyze_incomplete(project, &metadata).unwrap();
        let scratch = tempfile::tempdir().unwrap();
        let original = scratch.path().join("original.mp4");
        let mut joined = fs::File::create(&original).unwrap();
        let segment = &recording.recoverable_segments[0];
        for path in segment
            .display_init_segment
            .iter()
            .chain(&segment.display_fragments)
        {
            std::io::copy(&mut fs::File::open(path).unwrap(), &mut joined).unwrap();
        }
        drop(joined);
        let expected = packets(&original);
        assert_eq!(expected.len(), 60);
        RecoveryManager::finalize_with_preparing(&recording, job).unwrap();
        assert!(observer.publication_succeeded());
        drop(observer);
        drop(wait_for_recovery_lock(project));
        assert_eq!(packets(&project.join(OUTPUT)), expected);
        let workspaces: Vec<_> = fs::read_dir(project)
            .unwrap()
            .map(Result::unwrap)
            .filter(|entry| {
                entry
                    .file_name()
                    .to_string_lossy()
                    .starts_with(".recovery-")
            })
            .collect();
        assert_eq!(workspaces.len(), 1);
        assert!(!workspaces[0].path().join("original-segments").exists());
        assert!(matches!(
            RecordingMeta::load_for_project(project)
                .unwrap()
                .studio_meta()
                .unwrap()
                .status(),
            StudioRecordingStatus::Complete
        ));
    }

    #[test]
    fn inspected_preparing_finalization_matches_ordinary_configuration_behavior_after_edits() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::EditedConfiguration);
    }

    #[test]
    fn inspected_preparing_finalization_preserves_fresh_metadata_edits_and_declines_preview() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::EditedMetadata);
    }

    #[test]
    fn inspected_preparing_finalization_preserves_recovery_lock_contention_without_writes() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::HeldRecoveryLock);
    }

    #[test]
    fn inspected_preparing_finalization_declines_a_different_stopped_project() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::WrongStoppedProject);
    }

    #[test]
    fn inspected_preparing_finalization_rejects_stale_analysis_without_writes() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::StaleAnalysis);
    }

    #[test]
    fn inspected_preparing_finalization_preserves_requested_track_failure() {
        assert_preparing_entry_point_matches_ordinary(PreparingEntryCase::RequiredTrackFailure);
    }

    #[test]
    fn preparing_finalizer_revokes_sources_and_retains_lock_until_last_reader_closes() {
        use std::io::Read;

        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let completed = completed_preparing_fixture(project);
        let (job, observer) = PreparingStudioJob::claim(&completed, 42).unwrap();
        let metadata = RecordingMeta::load_for_project(project).unwrap();
        let recording = RecoveryManager::analyze_incomplete(project, &metadata).unwrap();
        let mut retained = None;
        RecoveryManager::finalize_with_publication(
            &recording,
            RecoveryPurpose::Finalize,
            copy_recovery_input_with_durability,
            |_, _| {
                let sources = match observer.latest() {
                    PreparingStudioState::Available(sources) => sources,
                    PreparingStudioState::Unavailable(reason) => panic!("{reason}"),
                    _ => panic!("Expected preparing sources before publication"),
                };
                let live = sources.live().unwrap();
                let video = live.video(0, PreparingVideoTrack::Display).unwrap();
                let (source, paths) = video.input().unwrap();
                let expected = fs::read(project.join("content/segments").join(&paths[0]))?;
                let mut reader = source.reader(&paths[0])?;
                let mut header = [0; 8];
                reader.read_exact(&mut header)?;
                assert_eq!(&header, &expected[..8]);
                retained = Some((sources.clone(), reader, expected));
                Ok(())
            },
            publish_recovery,
            RecoveryLock::acquire,
            Some(job),
        )
        .unwrap();
        assert!(matches!(observer.latest(), PreparingStudioState::Ended));
        let (sources, mut reader, expected) = retained.unwrap();
        assert!(sources.live().is_none());
        assert!(RecoveryLock::acquire(project).is_err());
        drop(sources);
        drop(observer);
        assert!(RecoveryLock::acquire(project).is_err());
        let mut remaining = Vec::new();
        reader.read_to_end(&mut remaining).unwrap();
        assert_eq!(remaining, expected[8..]);
        drop(reader);
        drop(wait_for_recovery_lock(project));
        let finalized = RecordingMeta::load_for_project(project).unwrap();
        assert!(matches!(
            finalized.studio_meta().unwrap().status(),
            StudioRecordingStatus::Complete
        ));
    }

    #[test]
    fn preparing_config_drift_declines_preview_without_failing_finalization() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let completed = completed_preparing_fixture(project);
        let (job, observer) = PreparingStudioJob::claim(&completed, 7).unwrap();
        let mut configuration = ProjectConfiguration::load(project).unwrap();
        configuration.timeline.as_mut().unwrap().segments[0].name = Some("Changed".into());
        configuration.write(project).unwrap();
        let metadata = RecordingMeta::load_for_project(project).unwrap();
        let recording = RecoveryManager::analyze_incomplete(project, &metadata).unwrap();
        RecoveryManager::finalize_with_publication(
            &recording,
            RecoveryPurpose::Finalize,
            copy_recovery_input_with_durability,
            |_, _| {
                assert!(matches!(
                    observer.latest(),
                    PreparingStudioState::Unavailable(_)
                ));
                Ok(())
            },
            publish_recovery,
            RecoveryLock::acquire,
            Some(job),
        )
        .unwrap();
        assert!(matches!(observer.latest(), PreparingStudioState::Ended));
        assert!(project.join(OUTPUT).is_file());
        assert!(RecoveryLock::acquire(project).is_ok());
    }

    #[test]
    fn preparing_finalizer_panic_revokes_capability_without_unlocking_live_reader() {
        use std::io::Read;

        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let completed = completed_preparing_fixture(project);
        let (job, observer) = PreparingStudioJob::claim(&completed, 8).unwrap();
        let metadata = RecordingMeta::load_for_project(project).unwrap();
        let recording = RecoveryManager::analyze_incomplete(project, &metadata).unwrap();
        let before = recovery_snapshot(project).unwrap();
        let mut retained = None;
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            RecoveryManager::finalize_with_publication(
                &recording,
                RecoveryPurpose::Finalize,
                copy_recovery_input_with_durability,
                |_, _| {
                    let sources = match observer.latest() {
                        PreparingStudioState::Available(sources) => sources,
                        PreparingStudioState::Unavailable(reason) => panic!("{reason}"),
                        _ => panic!("Expected preparing sources before injected failure"),
                    };
                    let live = sources.live().unwrap();
                    let video = live.video(0, PreparingVideoTrack::Display).unwrap();
                    let (source, paths) = video.input().unwrap();
                    let mut reader = source.reader(&paths[0])?;
                    let mut header = [0; 8];
                    reader.read_exact(&mut header)?;
                    retained = Some((sources.clone(), reader));
                    panic!("Injected finalizer interruption after source publication");
                },
                publish_recovery,
                RecoveryLock::acquire,
                Some(job),
            )
        }));
        assert!(result.is_err());
        assert!(matches!(observer.latest(), PreparingStudioState::Ended));
        let (sources, reader) = retained.unwrap();
        assert!(sources.live().is_none());
        drop(sources);
        assert!(RecoveryLock::acquire(project).is_err());
        drop(reader);
        assert!(RecoveryLock::acquire(project).is_ok());
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        assert!(project.join(DISPLAY).is_dir());
        assert!(!project.join(OUTPUT).exists());
    }

    #[test]
    fn preparing_drifted_completion_uses_ordinary_success_path() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let mut completed = completed_preparing_fixture(project);
        let (job, observer) = PreparingStudioJob::claim(&completed, 9).unwrap();
        let StudioRecordingMeta::MultipleSegments { inner } = &mut completed.meta else {
            panic!()
        };
        inner.segments[0].display.fps = 60;
        assert!(RecoveryManager::remux_stopped_with_preparing(&completed, job).unwrap());
        assert!(matches!(observer.latest(), PreparingStudioState::Ended));
        assert!(project.join(OUTPUT).is_file());
        assert!(RecoveryLock::acquire(project).is_ok());
    }

    #[test]
    fn a_stop_without_a_preparing_editor_retires_the_original_media_backup() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();

        assert!(RecoveryManager::remux_if_needed(project).unwrap());

        let workspaces: Vec<_> = fs::read_dir(project)
            .unwrap()
            .map(|entry| entry.unwrap().path())
            .filter(|path| {
                path.file_name()
                    .unwrap()
                    .to_string_lossy()
                    .starts_with(".recovery-")
            })
            .collect();
        assert_eq!(workspaces.len(), 1);
        assert!(!workspaces[0].join("original-segments").exists());
        let meta = RecordingMeta::load_for_project(project).unwrap();
        let StudioRecordingMeta::MultipleSegments { inner } = meta.studio_meta().unwrap() else {
            panic!()
        };
        let display = meta.path(&inner.segments[0].display.path);
        assert!(cap_enc_ffmpeg::remux::get_video_fps(&display).is_some());
    }

    #[test]
    fn studio_finalization_keeps_the_recorded_display_fps() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let mut meta = RecordingMeta::load_for_project(project).unwrap();
        let RecordingMetaInner::Studio(studio) = &mut meta.inner else {
            panic!()
        };
        let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
            panic!()
        };
        inner.segments[0].display.fps = 120;
        meta.save_for_project().unwrap();

        assert!(RecoveryManager::remux_if_needed(project).unwrap());
        let meta = RecordingMeta::load_for_project(project).unwrap();
        let StudioRecordingMeta::MultipleSegments { inner } = meta.studio_meta().unwrap() else {
            panic!()
        };
        let display = meta.path(&inner.segments[0].display.path);
        assert_ne!(cap_enc_ffmpeg::remux::get_video_fps(&display), Some(120));
        assert_eq!(inner.segments[0].display.fps, 120);
    }

    #[test]
    fn studio_finalization_without_a_recorded_fps_uses_the_base_rate_not_the_average() {
        // A 60 fps capture of a mostly static screen: short bursts on the
        // 60 fps grid between long holds, averaging well under 60 fps.
        let times = (0..4u64)
            .flat_map(|burst| (0..6u64).map(move |k| burst * 500_000 + k * 1_000_000 / 60));
        let directory = studio_project_with_frames(StudioRecordingStatus::NeedsRemux, 60, times);
        let project = directory.path();
        let mut meta = RecordingMeta::load_for_project(project).unwrap();
        let RecordingMetaInner::Studio(studio) = &mut meta.inner else {
            panic!()
        };
        let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
            panic!()
        };
        inner.segments[0].display.fps = 0;
        meta.save_for_project().unwrap();

        assert!(RecoveryManager::remux_if_needed(project).unwrap());
        let meta = RecordingMeta::load_for_project(project).unwrap();
        let StudioRecordingMeta::MultipleSegments { inner } = meta.studio_meta().unwrap() else {
            panic!()
        };
        let display = meta.path(&inner.segments[0].display.path);
        let average = cap_enc_ffmpeg::remux::get_video_fps(&display).unwrap();
        assert!(average < 30, "fixture averages {average} fps");
        assert_eq!(inner.segments[0].display.fps, 60);
    }

    #[test]
    fn studio_finalization_preserves_encoded_audio_samples_and_offsets() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let microphone = add_fragmented_audio(project, "audio-input", 90);
        let system_audio = add_fragmented_audio(project, "system_audio", 90);
        let original_audio = cap_audio::AudioData::from_file(&microphone).unwrap();
        let mut meta = RecordingMeta::load_for_project(project).unwrap();
        let RecordingMetaInner::Studio(studio) = &mut meta.inner else {
            panic!()
        };
        let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
            panic!()
        };
        inner.segments[0].mic = Some(AudioMeta {
            path: "content/segments/segment-0/audio-input.m4a".into(),
            start_time: Some(-0.125),
            device_id: Some("benchmark microphone".into()),
            gap_summary: None,
            digital_silence_ms: Some(190_000),
        });
        inner.segments[0].system_audio = Some(AudioMeta {
            path: "content/segments/segment-0/system_audio.m4a".into(),
            start_time: Some(0.25),
            device_id: None,
            gap_summary: None,
            digital_silence_ms: None,
        });
        meta.save_for_project().unwrap();

        assert!(RecoveryManager::remux_if_needed(project).unwrap());
        let meta = RecordingMeta::load_for_project(project).unwrap();
        let StudioRecordingMeta::MultipleSegments { inner } = meta.studio_meta().unwrap() else {
            panic!()
        };
        let segment = &inner.segments[0];
        let mic = segment.mic.as_ref().unwrap();
        assert_eq!(
            mic.path.as_str(),
            "content/segments/segment-0/audio-input.m4a"
        );
        assert_eq!(mic.start_time, Some(-0.125));
        assert_eq!(mic.device_id.as_deref(), Some("benchmark microphone"));
        assert_eq!(mic.digital_silence_ms, Some(190_000));
        assert_eq!(
            segment.system_audio.as_ref().unwrap().start_time,
            Some(0.25)
        );
        for path in [&microphone, &system_audio] {
            let audio = cap_audio::AudioData::from_file(path).unwrap();
            assert_eq!(audio.channels(), original_audio.channels());
            assert_eq!(audio.samples(), original_audio.samples());
        }
        let backup = fs::read_dir(project)
            .unwrap()
            .map(|entry| entry.unwrap().path())
            .find(|path| {
                path.file_name()
                    .unwrap()
                    .to_string_lossy()
                    .starts_with(".recovery-")
            })
            .unwrap();
        // A stop without a preparing editor retires the original backup once
        // the published tracks above are in place.
        assert!(!backup.join("original-segments").exists());
    }

    #[test]
    fn studio_finalization_preserves_a_live_managed_audio_decoder() {
        use cap_audio::{AudioStream, ChunkRead};
        use std::sync::{Arc, atomic::AtomicBool};

        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let microphone = add_fragmented_audio(project, "audio-input", 2880);
        assert!(microphone.metadata().unwrap().len() > 4 * 64 * 1024);
        let original_audio = cap_audio::AudioData::from_file(&microphone).unwrap();
        let mut meta = RecordingMeta::load_for_project(project).unwrap();
        let RecordingMetaInner::Studio(studio) = &mut meta.inner else {
            panic!()
        };
        let StudioRecordingMeta::MultipleSegments { inner } = studio.as_mut() else {
            panic!()
        };
        inner.segments[0].mic = Some(AudioMeta {
            path: "content/segments/segment-0/audio-input.m4a".into(),
            start_time: Some(-0.125),
            device_id: None,
            gap_summary: None,
            digital_silence_ms: None,
        });
        meta.save_for_project().unwrap();
        let recording = RecoveryManager::analyze_incomplete(project, &meta).unwrap();
        let source = RelocatableSource::new(project.join("content/segments")).unwrap();
        let mut audio = AudioStream::open_relocatable(
            &source,
            [Path::new("segment-0/audio-input.m4a")],
            Arc::new(AtomicBool::new(false)),
        )
        .unwrap();
        let ChunkRead::Chunk(prefix) = audio.read_chunk(4096).unwrap() else {
            panic!()
        };
        assert_eq!(prefix.source_start_sample, 0);
        let mut decoded = prefix.samples;
        let recovered =
            RecoveryManager::finalize_with_relocatable_source(&recording, &source).unwrap();
        assert_eq!(recovered.project_path, project);
        loop {
            match audio.read_chunk(4096).unwrap() {
                ChunkRead::Chunk(chunk) => {
                    assert_eq!(
                        chunk.source_start_sample as usize,
                        decoded.len() / usize::from(original_audio.channels())
                    );
                    assert_eq!(chunk.channels, original_audio.channels());
                    decoded.extend(chunk.samples);
                }
                ChunkRead::Eof { next_sample } => {
                    assert_eq!(
                        next_sample as usize,
                        decoded.len() / usize::from(original_audio.channels())
                    );
                    break;
                }
            }
        }
        let expected = original_audio
            .samples()
            .iter()
            .map(|sample| sample.to_bits());
        assert!(decoded.iter().map(|sample| sample.to_bits()).eq(expected));
        let finalized = cap_audio::AudioData::from_file(&microphone).unwrap();
        assert!(
            finalized
                .samples()
                .iter()
                .map(|sample| sample.to_bits())
                .eq(original_audio
                    .samples()
                    .iter()
                    .map(|sample| sample.to_bits()))
        );
        let persisted = RecordingMeta::load_for_project(project).unwrap();
        assert_eq!(
            serde_json::to_value(persisted.studio_meta()).unwrap(),
            serde_json::to_value(&recovered.meta).unwrap()
        );
    }

    #[test]
    fn recovery_copies_have_independent_bytes_and_preserve_existing_destinations() {
        let directory = tempfile::tempdir().unwrap();
        let source = directory.path().join("source");
        let destination = directory.path().join("destination");
        fs::write(&source, b"original recording").unwrap();
        copy_recovery_input(&source, &destination).unwrap();
        fs::write(&destination, b"staged recording").unwrap();
        assert_eq!(fs::read(&source).unwrap(), b"original recording");
        assert!(copy_recovery_input(&source, &destination).is_err());
        assert_eq!(fs::read(&destination).unwrap(), b"staged recording");
    }

    fn change_fragment_bytes(project: &Path) {
        let path = project.join(FRAGMENT);
        let modified = fs::metadata(&path).unwrap().modified().unwrap();
        let mut bytes = fs::read(&path).unwrap();
        *bytes.last_mut().unwrap() ^= 1;
        fs::write(&path, bytes).unwrap();
        fs::OpenOptions::new()
            .write(true)
            .open(&path)
            .unwrap()
            .set_times(fs::FileTimes::new().set_modified(modified))
            .unwrap();
        assert_eq!(fs::metadata(path).unwrap().modified().unwrap(), modified);
    }

    fn assert_unpublished(project: &Path) {
        assert!(project.join(DISPLAY).is_dir());
        assert!(!project.join(OUTPUT).exists());
        assert!(!project.join(RECOVERY_PUBLICATION).exists());
        assert!(fs::read_dir(project).unwrap().all(|entry| {
            !entry
                .unwrap()
                .file_name()
                .to_string_lossy()
                .starts_with(".recovery-")
        }));
    }

    fn assert_staged_output(staged: &Path) {
        validate_recovered_track(&staged.join(OUTPUT), ffmpeg::media::Type::Video).unwrap();
        assert!(matches!(
            RecordingMeta::load_for_project(staged)
                .unwrap()
                .studio_meta()
                .unwrap()
                .status(),
            StudioRecordingStatus::Complete
        ));
    }

    #[derive(Clone, Copy)]
    enum SourceChange {
        FragmentBytes,
        AddedSegment,
        RemovedFragment,
    }

    impl SourceChange {
        fn apply(self, project: &Path) {
            match self {
                Self::FragmentBytes => change_fragment_bytes(project),
                Self::AddedSegment => {
                    fs::create_dir(project.join("content/segments/segment-1")).unwrap();
                }
                Self::RemovedFragment => fs::remove_file(project.join(FRAGMENT)).unwrap(),
            }
        }
    }

    fn check_persistent_source_changes(during_copy: bool) {
        for change in [
            SourceChange::FragmentBytes,
            SourceChange::AddedSegment,
            SourceChange::RemovedFragment,
        ] {
            let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
            let project = directory.path();
            let recording = RecoveryManager::inspect_recording(project).unwrap();
            let expected = RefCell::new(None);
            let reached_final_check = Cell::new(false);
            let error = RecoveryManager::finalize_with_operations(
                &recording,
                RecoveryPurpose::Finalize,
                |source, destination, durability| {
                    copy_recovery_input_with_durability(source, destination, durability)?;
                    if during_copy && source == project.join("content") {
                        change.apply(project);
                        *expected.borrow_mut() = Some(recovery_snapshot(project)?);
                    }
                    Ok(())
                },
                |source, staged| {
                    assert_staged_output(staged);
                    reached_final_check.set(true);
                    if !during_copy {
                        change.apply(source);
                        *expected.borrow_mut() = Some(recovery_snapshot(source)?);
                    }
                    Ok(())
                },
            )
            .unwrap_err();
            assert!(matches!(error, RecoveryError::Validation(message)
                if message == "Recording changed before publication"));
            assert!(reached_final_check.get());
            assert_eq!(
                recovery_snapshot(project).unwrap(),
                expected.into_inner().unwrap()
            );
            assert_unpublished(project);
        }
    }

    #[test]
    fn persistent_source_changes_during_copy_cannot_publish() {
        check_persistent_source_changes(true);
    }

    #[test]
    fn persistent_source_changes_before_publication_cannot_publish() {
        check_persistent_source_changes(false);
    }

    #[test]
    fn failed_copy_preserves_originals_and_removes_partial_stage() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let recording = RecoveryManager::inspect_recording(project).unwrap();
        let before = recovery_snapshot(project).unwrap();
        let error = RecoveryManager::finalize_with_operations(
            &recording,
            RecoveryPurpose::Finalize,
            |source, destination, _| {
                assert_eq!(source, project.join("content"));
                fs::create_dir(destination)?;
                fs::write(destination.join("partial.m4s"), b"partial copy")?;
                Err(io::Error::other("injected copy failure").into())
            },
            |_, _| panic!("failed copy must not reach the final source check"),
        )
        .unwrap_err();
        assert!(matches!(error, RecoveryError::Io(error)
            if error.to_string() == "injected copy failure"));
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        assert_unpublished(project);
    }

    #[test]
    fn independently_changed_staged_bytes_cannot_publish() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let recording = RecoveryManager::inspect_recording(project).unwrap();
        let before = recovery_snapshot(project).unwrap();
        let error = RecoveryManager::finalize_with_operations(
            &recording,
            RecoveryPurpose::Finalize,
            |source, destination, durability| {
                copy_recovery_input_with_durability(source, destination, durability)?;
                if source == project.join("content") {
                    change_fragment_bytes(destination.parent().unwrap());
                }
                Ok(())
            },
            |_, _| panic!("changed staged bytes must not reach the final source check"),
        )
        .unwrap_err();
        assert!(matches!(error, RecoveryError::Validation(message)
            if message == "Recording changed while copying"));
        assert_eq!(recovery_snapshot(project).unwrap(), before);
        assert_unpublished(project);
    }

    #[test]
    fn late_required_track_failure_preserves_originals_without_publication() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let recording = RecoveryManager::inspect_recording(project).unwrap();
        let expected = RefCell::new(None);
        let error = RecoveryManager::finalize_with_operations(
            &recording,
            RecoveryPurpose::Finalize,
            copy_recovery_input_with_durability,
            |source, staged| {
                assert_staged_output(staged);
                fs::write(
                    source.join("recording-diagnostics.json"),
                    br#"{"version":2,"segments":[{"trackFailures":[{"track":"display","stage":"stop","error":"injected late failure"}]}]}"#,
                )?;
                *expected.borrow_mut() = Some(recovery_snapshot(source)?);
                Ok(())
            },
        )
        .unwrap_err();
        assert!(matches!(error, RecoveryError::RequiredTrackFailure(_)));
        assert_eq!(
            recovery_snapshot(project).unwrap(),
            expected.into_inner().unwrap()
        );
        assert_unpublished(project);
    }

    #[test]
    fn clean_finalization_accepts_source_restored_identically_before_publication() {
        let directory = playable_studio_project(StudioRecordingStatus::NeedsRemux);
        let project = directory.path();
        let recording = RecoveryManager::inspect_recording(project).unwrap();
        let before = recovery_snapshot(project).unwrap();
        let raw = fs::read(project.join(FRAGMENT)).unwrap();
        let reached_final_check = Cell::new(false);
        RecoveryManager::finalize_with_operations(
            &recording,
            RecoveryPurpose::Finalize,
            |source, destination, durability| {
                copy_recovery_input_with_durability(source, destination, durability)?;
                if source == project.join("content") {
                    change_fragment_bytes(project);
                }
                Ok(())
            },
            |source, staged| {
                assert_staged_output(staged);
                assert_ne!(recovery_snapshot(source)?, before);
                fs::write(source.join(FRAGMENT), &raw)?;
                assert_eq!(recovery_snapshot(source)?, before);
                reached_final_check.set(true);
                Ok(())
            },
        )
        .unwrap();
        assert!(reached_final_check.get());
        assert_staged_output(project);
        let workspace = fs::read_dir(project)
            .unwrap()
            .map(|entry| entry.unwrap().path())
            .find(|path| path.join("original-segments").is_dir())
            .unwrap();
        for (path, digest) in before {
            let backup = if let Ok(relative) = path.strip_prefix("content/segments") {
                workspace.join("original-segments").join(relative)
            } else {
                continue;
            };
            if let Some(digest) = digest {
                assert_eq!(
                    blake3::hash(&fs::read(backup).unwrap())
                        .as_bytes()
                        .as_slice(),
                    digest
                );
            } else {
                assert!(backup.is_dir());
            }
        }
    }

    #[test]
    fn full_validation_keeps_early_source_change_rejection() {
        for (purpose, status) in [
            (RecoveryPurpose::Recover, StudioRecordingStatus::NeedsRemux),
            (RecoveryPurpose::Finalize, StudioRecordingStatus::InProgress),
        ] {
            let directory = playable_studio_project(status);
            let project = directory.path();
            let recording = RecoveryManager::inspect_recording(project).unwrap();
            let expected = RefCell::new(None);
            let error = RecoveryManager::finalize_with_operations(
                &recording,
                purpose,
                |source, destination, durability| {
                    copy_recovery_input_with_durability(source, destination, durability)?;
                    if source == project.join("content") {
                        change_fragment_bytes(project);
                        *expected.borrow_mut() = Some(recovery_snapshot(project)?);
                    }
                    Ok(())
                },
                |_, _| panic!("full validation must reject before source restoration is possible"),
            )
            .unwrap_err();
            assert!(matches!(error, RecoveryError::Validation(message)
                if message == "Recording changed while copying"));
            assert_eq!(
                recovery_snapshot(project).unwrap(),
                expected.into_inner().unwrap()
            );
            assert_unpublished(project);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{
        RecoveryManager, RecoveryPurpose, StudioRecordingStatus, VideoValidation, replace_file,
        start_time_or_display_fallback, valid_recovered_audio, validate_recovered_audio_in_order,
        validate_recovery_track,
    };
    use std::fs;
    use tempfile::tempdir;

    #[test]
    fn only_clean_finalization_uses_bounded_video_validation() {
        for status in [
            None,
            Some(StudioRecordingStatus::InProgress),
            Some(StudioRecordingStatus::NeedsRemux),
            Some(StudioRecordingStatus::Complete),
            Some(StudioRecordingStatus::Failed {
                error: "capture failed".into(),
            }),
        ] {
            assert_eq!(
                RecoveryPurpose::Recover.video_validation(status.clone()),
                VideoValidation::Full
            );
            let expected = if matches!(status, Some(StudioRecordingStatus::NeedsRemux)) {
                VideoValidation::Bounded
            } else {
                VideoValidation::Full
            };
            assert_eq!(RecoveryPurpose::Finalize.video_validation(status), expected);
        }
    }

    #[test]
    fn bounded_video_validation_rejects_empty_and_unplayable_media() {
        let directory = tempdir().unwrap();
        let path = directory.path().join("display.mp4");
        for bytes in [b"".as_slice(), b"invalid video".as_slice()] {
            fs::write(&path, bytes).unwrap();
            assert!(
                validate_recovery_track(
                    &path,
                    ffmpeg::media::Type::Video,
                    VideoValidation::Bounded
                )
                .is_err()
            );
            assert_eq!(fs::read(&path).unwrap(), bytes);
        }
    }

    #[test]
    fn completed_instant_audio_requirement_preserves_inputs_when_audio_is_missing() {
        let directory = tempdir().unwrap();
        let project = directory.path();
        let display = project.join("content/display");
        fs::create_dir_all(&display).unwrap();
        fs::write(display.join("init.mp4"), b"original video init").unwrap();
        let output = project.join("content/output.mp4");
        fs::write(&output, b"original output").unwrap();
        let before = super::recovery_snapshot(project).unwrap();

        let error = RecoveryManager::finalize_instant_output_with_completion(
            &display,
            &project.join("content/audio"),
            &output,
            Some((project.to_path_buf(), true)),
        )
        .unwrap_err();

        assert!(error.to_string().contains("Missing required Instant audio"));
        assert_eq!(super::recovery_snapshot(project).unwrap(), before);
        assert!(fs::read_dir(project).unwrap().all(|entry| {
            !entry
                .unwrap()
                .file_name()
                .to_string_lossy()
                .starts_with(".recovery-")
        }));
    }

    #[test]
    fn completed_instant_rejects_other_paths_in_the_same_project_without_mutation() {
        let directory = tempdir().unwrap();
        let project = directory.path();
        let content = project.join("content");
        fs::create_dir(&content).unwrap();
        fs::write(content.join("original.mp4"), b"original output").unwrap();
        let before = super::recovery_snapshot(project).unwrap();

        for (display, audio, output) in [
            ("other", "audio", "output.mp4"),
            ("display", "other", "output.mp4"),
            ("display", "audio", "original.mp4"),
        ] {
            let error = RecoveryManager::finalize_instant_output_with_completion(
                &content.join(display),
                &content.join(audio),
                &content.join(output),
                Some((project.to_path_buf(), false)),
            )
            .unwrap_err();
            assert!(
                error
                    .to_string()
                    .contains("must use the recorded track and output paths")
            );
            assert_eq!(super::recovery_snapshot(project).unwrap(), before);
            assert_eq!(fs::read_dir(project).unwrap().count(), 1);
        }
    }

    fn complete_m4s_fragment() -> Vec<u8> {
        let mut fragment = Vec::new();
        for name in [b"moof", b"mdat"] {
            fragment.extend_from_slice(&72u32.to_be_bytes());
            fragment.extend_from_slice(name);
            fragment.extend_from_slice(&[0; 64]);
        }
        fragment
    }

    #[test]
    fn recovery_keeps_a_completed_fragment_listed_pending_after_an_earlier_valid_fragment() {
        let dir = tempdir().unwrap();
        let fragment = complete_m4s_fragment();
        fs::write(dir.path().join("init.mp4"), [0; 128]).unwrap();
        for name in ["segment_001.m4s", "segment_002.m4s"] {
            fs::write(dir.path().join(name), &fragment).unwrap();
        }
        let manifest = serde_json::to_vec(&serde_json::json!({
            "version": 5,
            "type": "m4s_segments",
            "init_segment": "init.mp4",
            "segments": [
                {"path": "segment_001.m4s", "is_complete": true, "file_size": fragment.len()},
                {"path": "segment_002.m4s", "is_complete": false, "file_size": null}
            ]
        }))
        .unwrap();
        fs::write(dir.path().join("manifest.json"), manifest).unwrap();
        let recovered = RecoveryManager::find_complete_fragments_with_init(dir.path());
        assert_eq!(
            recovered.fragments,
            ["segment_001.m4s", "segment_002.m4s"].map(|name| dir.path().join(name))
        );
    }

    #[test]
    fn recovery_still_rejects_pending_and_mismatched_fragments_that_are_not_complete() {
        let dir = tempdir().unwrap();
        let fragment = complete_m4s_fragment();
        fs::write(dir.path().join("init.mp4"), [0; 128]).unwrap();
        fs::write(dir.path().join("segment_001.m4s"), &fragment).unwrap();
        fs::write(dir.path().join("segment_002.m4s"), &fragment).unwrap();
        fs::write(
            dir.path().join("segment_003.m4s"),
            &fragment[..fragment.len() - 1],
        )
        .unwrap();
        let manifest = serde_json::to_vec(&serde_json::json!({
            "version": 5,
            "type": "m4s_segments",
            "init_segment": "init.mp4",
            "segments": [
                {"path": "segment_001.m4s", "is_complete": true, "file_size": fragment.len()},
                {"path": "segment_002.m4s", "is_complete": true, "file_size": fragment.len() + 1},
                {"path": "segment_003.m4s", "is_complete": false, "file_size": null}
            ]
        }))
        .unwrap();
        fs::write(dir.path().join("manifest.json"), manifest).unwrap();
        let recovered = RecoveryManager::find_complete_fragments_with_init(dir.path());
        assert_eq!(recovered.fragments, [dir.path().join("segment_001.m4s")]);
    }

    #[test]
    fn recovery_includes_complete_fragments_missing_from_the_last_manifest() {
        let dir = tempdir().unwrap();
        let fragment = complete_m4s_fragment();
        fs::write(dir.path().join("init.mp4"), [0; 128]).unwrap();
        for name in [
            "segment_001.m4s",
            "segment_002.m4s",
            "segment_999.m4s",
            "segment_1000.m4s",
        ] {
            fs::write(dir.path().join(name), &fragment).unwrap();
        }
        fs::write(
            dir.path().join("segment_1001.m4s"),
            &fragment[..fragment.len() - 1],
        )
        .unwrap();
        let manifest = serde_json::to_vec(&serde_json::json!({
            "version": 5,
            "type": "m4s_segments",
            "init_segment": "init.mp4",
            "segments": [
                {"path": "segment_001.m4s", "is_complete": true, "file_size": fragment.len()},
                {"path": "segment_002.m4s", "is_complete": true, "file_size": fragment.len() + 1}
            ]
        }))
        .unwrap();
        fs::write(dir.path().join("manifest.json"), &manifest).unwrap();

        let recovered = RecoveryManager::find_complete_fragments_with_init(dir.path());
        assert_eq!(
            recovered.fragments,
            ["segment_001.m4s", "segment_999.m4s", "segment_1000.m4s"]
                .map(|name| dir.path().join(name))
        );
        assert_eq!(
            fs::read(dir.path().join("manifest.json")).unwrap(),
            manifest
        );
        assert!(dir.path().join("segment_1001.m4s").is_file());
    }

    #[test]
    fn recovery_reconstructs_only_complete_fragments_when_manifest_has_no_valid_entries() {
        let dir = tempdir().unwrap();
        let fragment = complete_m4s_fragment();
        let partial = &fragment[..fragment.len() - 1];
        fs::write(dir.path().join("init.mp4"), [0; 128]).unwrap();
        fs::write(dir.path().join("segment_001.m4s"), &fragment).unwrap();
        fs::write(dir.path().join("segment_999.m4s"), &fragment).unwrap();
        fs::write(dir.path().join("segment_1000.m4s"), &fragment).unwrap();
        fs::write(dir.path().join("segment_002.m4s"), partial).unwrap();
        let manifest = serde_json::to_vec(&serde_json::json!({
            "version": 5,
            "type": "m4s_segments",
            "init_segment": "init.mp4",
            "segments": [
                {"path": "segment_001.m4s", "is_complete": false, "file_size": fragment.len()},
                {"path": "segment_999.m4s", "is_complete": false, "file_size": fragment.len()},
                {"path": "segment_1000.m4s", "is_complete": false, "file_size": fragment.len()},
                {"path": "segment_002.m4s", "is_complete": false, "file_size": partial.len()}
            ]
        }))
        .unwrap();
        fs::write(dir.path().join("manifest.json"), &manifest).unwrap();

        let recovered = RecoveryManager::find_complete_fragments_with_init(dir.path());

        assert_eq!(
            recovered.fragments,
            ["segment_001.m4s", "segment_999.m4s", "segment_1000.m4s"]
                .map(|name| dir.path().join(name))
        );
        assert_eq!(recovered.init_segment, Some(dir.path().join("init.mp4")));
        assert_eq!(
            fs::read(dir.path().join("manifest.json")).unwrap(),
            manifest
        );
        assert!(dir.path().join("segment_002.m4s").is_file());
    }

    #[test]
    fn recovery_rejects_partial_only_fragments_when_manifest_has_no_valid_entries() {
        let dir = tempdir().unwrap();
        let fragment = complete_m4s_fragment();
        let partial = &fragment[..fragment.len() - 1];
        fs::write(dir.path().join("init.mp4"), [0; 128]).unwrap();
        fs::write(dir.path().join("segment_001.m4s"), partial).unwrap();
        let manifest = serde_json::to_vec(&serde_json::json!({
            "version": 5,
            "type": "m4s_segments",
            "init_segment": "init.mp4",
            "segments": [
                {"path": "segment_001.m4s", "is_complete": false, "file_size": partial.len()}
            ]
        }))
        .unwrap();
        fs::write(dir.path().join("manifest.json"), &manifest).unwrap();

        let recovered = RecoveryManager::find_complete_fragments_with_init(dir.path());

        assert!(recovered.fragments.is_empty());
        assert_eq!(
            fs::read(dir.path().join("manifest.json")).unwrap(),
            manifest
        );
        assert!(dir.path().join("segment_001.m4s").is_file());
    }

    #[test]
    fn recovery_finds_complete_fragments_without_a_readable_manifest() {
        for manifest in [None, Some("{interrupted")] {
            let dir = tempdir().unwrap();
            let fragment = complete_m4s_fragment();
            fs::write(dir.path().join("init.mp4"), [0; 128]).unwrap();
            fs::write(dir.path().join("segment_001.m4s"), &fragment).unwrap();
            fs::write(
                dir.path().join("segment_002.m4s"),
                &fragment[..fragment.len() - 1],
            )
            .unwrap();
            if let Some(manifest) = manifest {
                fs::write(dir.path().join("manifest.json"), manifest).unwrap();
            }

            let recovered = RecoveryManager::find_complete_fragments_with_init(dir.path());

            assert_eq!(recovered.fragments, [dir.path().join("segment_001.m4s")]);
            assert_eq!(recovered.init_segment, Some(dir.path().join("init.mp4")));
            assert_eq!(
                fs::read_to_string(dir.path().join("manifest.json")).ok(),
                manifest.map(str::to_string)
            );
            assert!(dir.path().join("segment_002.m4s").is_file());
        }
    }

    #[test]
    fn replace_file_overwrites_existing_destination() {
        let dir = tempdir().unwrap();
        let src = dir.path().join("source.tmp");
        let dst = dir.path().join("destination.mp4");

        fs::write(&src, b"new").unwrap();
        fs::write(&dst, b"old").unwrap();

        replace_file(&src, &dst).unwrap();

        assert_eq!(fs::read(&dst).unwrap(), b"new");
        assert!(!src.exists());
    }

    #[test]
    fn recovered_audio_keeps_valid_media_smaller_than_legacy_threshold() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("quiet.wav");
        let samples = [0u8; 32];
        let mut bytes = Vec::new();
        bytes.extend_from_slice(b"RIFF");
        bytes.extend_from_slice(&(36 + samples.len() as u32).to_le_bytes());
        bytes.extend_from_slice(b"WAVEfmt ");
        bytes.extend_from_slice(&16u32.to_le_bytes());
        bytes.extend_from_slice(&1u16.to_le_bytes());
        bytes.extend_from_slice(&1u16.to_le_bytes());
        bytes.extend_from_slice(&8000u32.to_le_bytes());
        bytes.extend_from_slice(&16000u32.to_le_bytes());
        bytes.extend_from_slice(&2u16.to_le_bytes());
        bytes.extend_from_slice(&16u16.to_le_bytes());
        bytes.extend_from_slice(b"data");
        bytes.extend_from_slice(&(samples.len() as u32).to_le_bytes());
        bytes.extend_from_slice(&samples);
        fs::write(&path, &bytes).unwrap();

        assert!(bytes.len() < 500);
        assert!(valid_recovered_audio(&path));
    }

    #[test]
    fn parallel_audio_validation_reports_the_first_failure_in_track_order() {
        let dir = tempdir().unwrap();
        let mut bytes = Vec::new();
        bytes.extend_from_slice(b"RIFF");
        bytes.extend_from_slice(&68u32.to_le_bytes());
        bytes.extend_from_slice(b"WAVEfmt ");
        bytes.extend_from_slice(&16u32.to_le_bytes());
        bytes.extend_from_slice(&1u16.to_le_bytes());
        bytes.extend_from_slice(&1u16.to_le_bytes());
        bytes.extend_from_slice(&8000u32.to_le_bytes());
        bytes.extend_from_slice(&16000u32.to_le_bytes());
        bytes.extend_from_slice(&2u16.to_le_bytes());
        bytes.extend_from_slice(&16u16.to_le_bytes());
        bytes.extend_from_slice(b"data");
        bytes.extend_from_slice(&32u32.to_le_bytes());
        bytes.extend_from_slice(&[0u8; 32]);
        let tracks = ["valid-0", "missing-1", "valid-2", "missing-3", "missing-4"]
            .map(|name| dir.path().join(format!("{name}.wav")));
        for path in tracks
            .iter()
            .filter(|path| path.to_string_lossy().contains("valid-"))
        {
            fs::write(path, &bytes).unwrap();
        }
        let tracks = tracks.iter().collect::<Vec<_>>();

        for _ in 0..16 {
            let error = validate_recovered_audio_in_order(&tracks)
                .unwrap_err()
                .to_string();
            assert!(error.contains("missing-1.wav"), "{error}");
        }
        assert!(validate_recovered_audio_in_order(&[tracks[0], tracks[2]]).is_ok());
        assert!(validate_recovered_audio_in_order(&[]).is_ok());
    }

    #[test]
    fn recovered_audio_rejects_large_corrupt_media() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("corrupt.ogg");
        fs::write(&path, [0u8; 1024]).unwrap();

        assert!(!valid_recovered_audio(&path));
    }

    #[test]
    fn start_time_fallback_prefers_original_value() {
        let original = Some(0.8);
        let display = Some(0.4);
        assert_eq!(start_time_or_display_fallback(original, display), Some(0.8),);
    }

    #[test]
    fn start_time_fallback_returns_display_value_when_original_missing() {
        let display = Some(0.4374473);
        assert_eq!(
            start_time_or_display_fallback(None, display),
            Some(0.4374473),
            "mic/system audio start_time must align with display when unknown \
             so the editor's offset calculation (latest - start_time) stays at 0",
        );
    }

    #[test]
    fn start_time_fallback_returns_none_when_display_missing() {
        assert_eq!(start_time_or_display_fallback(None, None), None);
    }
}

#[cfg(test)]
mod empty_orphan_segment_tests {
    use super::*;
    use cap_enc_ffmpeg::segmented_stream::{SegmentedVideoEncoder, SegmentedVideoEncoderConfig};

    /// Encode a short fragmented video track so the segment passes the same
    /// media probes a real recording does.
    fn write_fragmented_track(segment_path: &Path, track: &str) {
        ffmpeg::init().unwrap();
        std::fs::create_dir_all(segment_path).unwrap();

        let mut encoder = SegmentedVideoEncoder::init(
            segment_path.join(track),
            cap_media_info::VideoInfo {
                pixel_format: cap_media_info::Pixel::NV12,
                width: 320,
                height: 240,
                time_base: ffmpeg::Rational(1, 1_000_000),
                frame_rate: ffmpeg::Rational(30, 1),
            },
            SegmentedVideoEncoderConfig {
                segment_duration: Duration::from_secs(1),
                ..Default::default()
            },
        )
        .unwrap();

        for index in 0..60 {
            let mut frame = ffmpeg::frame::Video::new(ffmpeg::format::Pixel::NV12, 320, 240);
            frame.data_mut(0).fill(32 + index as u8);
            frame.data_mut(1).fill(128);
            encoder
                .queue_frame(frame, Duration::from_micros(index * 1_000_000 / 30))
                .unwrap();
        }

        encoder.finish().unwrap();
        assert!(!encoder.completed_segments().is_empty());
    }

    fn write_recording_meta(project: &Path, segment_count: usize) {
        let segments = (0..segment_count)
            .map(|index| MultipleSegment {
                display: VideoMeta {
                    path: RelativePathBuf::from(format!(
                        "content/segments/segment-{index}/display.mp4"
                    )),
                    fps: 30,
                    start_time: None,
                    device_id: None,
                },
                camera: None,
                mic: None,
                system_audio: None,
                cursor: None,
                keyboard: None,
                display_notch: None,
            })
            .collect();

        let meta = RecordingMeta {
            platform: None,
            project_path: project.to_path_buf(),
            pretty_name: "Test Recording".to_string(),
            sharing: None,
            upload: None,
            inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
                inner: MultipleSegments {
                    segments,
                    cursors: Cursors::default(),
                    status: Some(StudioRecordingStatus::NeedsRemux),
                },
            })),
        };

        std::fs::write(
            project.join("recording-meta.json"),
            serde_json::to_string_pretty(&meta).unwrap(),
        )
        .unwrap();
    }

    /// A resume that fails after `create_next` has allocated the segment
    /// directory but before it has written any frames leaves that directory
    /// behind, empty. Recovery has to ignore it, otherwise the segment that
    /// does hold footage is thrown away with it.
    #[test]
    fn empty_orphan_segment_directory_does_not_block_recovery() {
        let directory = tempfile::tempdir().unwrap();
        let project = directory.path();

        write_fragmented_track(&project.join("content/segments/segment-0"), "display");
        std::fs::create_dir_all(project.join("content/segments/segment-1")).unwrap();
        write_recording_meta(project, 1);

        let incomplete = RecoveryManager::inspect_recording(project)
            .expect("a recording with one recoverable segment must be detected");
        assert_eq!(
            incomplete.recoverable_segments.len(),
            1,
            "the empty segment directory must not be collected"
        );

        RecoveryManager::require_recoverable_tracks(&incomplete)
            .expect("an empty orphan segment directory must not make the recording unrecoverable");
    }

    /// The guard the fix must not disarm: a segment directory that still holds
    /// footage but never made it into the recoverable set is a real
    /// inconsistency, and recovering around it would silently drop that
    /// footage from the recording.
    ///
    /// The metadata deliberately declares a single segment so that validation
    /// reaches the directory-level guard. Declaring two would fail earlier with
    /// "Missing display segment 1" and never exercise the check under test.
    #[test]
    fn segment_directory_with_footage_outside_the_recoverable_set_is_still_fatal() {
        let directory = tempfile::tempdir().unwrap();
        let project = directory.path();

        write_fragmented_track(&project.join("content/segments/segment-0"), "display");
        write_fragmented_track(&project.join("content/segments/segment-1"), "display");
        write_recording_meta(project, 1);

        let mut incomplete = RecoveryManager::inspect_recording(project)
            .expect("both populated segments must be detected");
        assert_eq!(incomplete.recoverable_segments.len(), 2);

        incomplete
            .recoverable_segments
            .retain(|segment| segment.index == 0);

        let error = RecoveryManager::require_recoverable_tracks(&incomplete).unwrap_err();

        assert!(
            error
                .to_string()
                .contains("Unrecoverable display segment 1"),
            "a populated but uncollected segment must still fail validation, got: {error}"
        );
    }

    /// A directory holding only a track other than the display is not an empty
    /// orphan. Skipping it would let recovery publish a recording that silently
    /// omits that footage, so it stays fatal.
    #[test]
    fn segment_directory_holding_only_non_display_media_is_still_fatal() {
        let directory = tempfile::tempdir().unwrap();
        let project = directory.path();

        write_fragmented_track(&project.join("content/segments/segment-0"), "display");
        write_fragmented_track(&project.join("content/segments/segment-1"), "camera");
        write_recording_meta(project, 1);

        let incomplete =
            RecoveryManager::inspect_recording(project).expect("the display segment must be found");
        assert_eq!(
            incomplete.recoverable_segments.len(),
            1,
            "a camera-only segment has no display fragments to collect"
        );

        let error = RecoveryManager::require_recoverable_tracks(&incomplete).unwrap_err();

        assert!(
            error
                .to_string()
                .contains("Unrecoverable display segment 1"),
            "a segment holding camera media must still fail validation, got: {error}"
        );
    }
}

#[cfg(test)]
mod required_track_failure_recovery_tests {
    use super::*;

    #[test]
    fn diagnostics_failure_blocks_recovery_without_modifying_partial_media() {
        let directory = tempfile::tempdir().unwrap();
        let media = directory.path().join("partial.m4a");
        std::fs::write(&media, b"preserved").unwrap();
        std::fs::write(directory.path().join("recording-diagnostics.json"),
            br#"{"version":1,"segments":[{"trackFailures":[{"track":"microphone","stage":"runtime","error":"failed"}]}]}"#).unwrap();
        assert!(RecoveryManager::require_no_track_failure(directory.path()).is_err());
        assert_eq!(std::fs::read(media).unwrap(), b"preserved");
    }

    #[test]
    fn unknown_or_unreadable_diagnostics_cannot_authorize_recovery() {
        let directory = tempfile::tempdir().unwrap();
        let path = directory.path().join("recording-diagnostics.json");
        for raw in [b"not-json".as_slice(), b"{}".as_slice()] {
            std::fs::write(&path, raw).unwrap();
            assert!(RecoveryManager::require_no_track_failure(directory.path()).is_err());
        }
        std::fs::remove_file(&path).unwrap();
        std::fs::create_dir(&path).unwrap();
        assert!(RecoveryManager::require_no_track_failure(directory.path()).is_err());
    }

    #[test]
    fn recording_without_failure_diagnostics_remains_eligible() {
        let directory = tempfile::tempdir().unwrap();
        assert!(RecoveryManager::require_no_track_failure(directory.path()).is_ok());
    }
}

#[cfg(test)]
mod transactional_recovery_tests {
    use super::*;
    use std::io::{Read, Seek, SeekFrom};

    fn publication_fixture() -> (tempfile::TempDir, PathBuf, PathBuf) {
        let temporary = tempfile::tempdir().unwrap();
        let project = temporary.path().join("project");
        let workspace = project.join(format!(".recovery-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(project.join("content/segments")).unwrap();
        create_private_recovery_dir(&workspace).unwrap();
        std::fs::create_dir_all(workspace.join("staged/content/segments")).unwrap();
        std::fs::write(project.join("content/segments/raw.m4s"), b"original raw").unwrap();
        std::fs::write(project.join("recording-meta.json"), b"original status").unwrap();
        std::fs::write(project.join("project-config.json"), b"original config").unwrap();
        std::fs::write(
            workspace.join("staged/content/segments/display.mp4"),
            b"validated output",
        )
        .unwrap();
        std::fs::write(workspace.join("staged/recording-meta.json"), b"complete").unwrap();
        std::fs::write(
            workspace.join("staged/project-config.json"),
            b"validated config",
        )
        .unwrap();
        (temporary, project, workspace)
    }

    fn interrupt_publication(project: &Path, workspace: &Path, after: usize) {
        let _lock = RecoveryLock::acquire(project).unwrap();
        let mut calls = 0;
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            publish_recovery_with(project, workspace, |source, destination| {
                assert_ne!(after, 0, "interrupted before the first rename");
                std::fs::rename(source, destination)?;
                calls += 1;
                assert_ne!(calls, after, "interrupted after publication rename");
                Ok(())
            })
        }));
        assert!(result.is_err());
        assert!(project.join(RECOVERY_PUBLICATION).is_file());
        assert!(workspace.join(RECOVERY_PUBLICATION_RECEIPT).is_file());
    }

    fn publication_fixture_with_version(
        version: u32,
        had_config: bool,
    ) -> (tempfile::TempDir, PathBuf, PathBuf) {
        publication_fixture_with_receipt(version, had_config, false)
    }

    fn publication_fixture_with_receipt(
        version: u32,
        had_config: bool,
        apple_double: bool,
    ) -> (tempfile::TempDir, PathBuf, PathBuf) {
        let fixture = publication_fixture();
        let (_, project, workspace) = &fixture;
        if !had_config {
            std::fs::remove_file(project.join("project-config.json")).unwrap();
        }
        if apple_double {
            std::fs::write(
                project.join("content/segments/._raw.m4s"),
                b"\x00\x05\x16\x07",
            )
            .unwrap();
        }
        interrupt_publication(project, workspace, 0);
        let stamp_version = match version {
            1 => RecoveryPublicationStampVersion::V1,
            2 => RecoveryPublicationStampVersion::V2,
            3 => RecoveryPublicationStampVersion::V3,
            _ => unreachable!(),
        };
        let receipt = RecoveryPublication {
            version,
            project: project.canonicalize().unwrap(),
            workspace: workspace.file_name().unwrap().to_str().unwrap().into(),
            original: recovery_publication_state_for_version(project, stamp_version).unwrap(),
            staged: recovery_publication_state_for_version(
                &workspace.join("staged"),
                stamp_version,
            )
            .unwrap(),
        };
        let bytes = serde_json::to_vec(&receipt).unwrap();
        std::fs::write(project.join(RECOVERY_PUBLICATION), &bytes).unwrap();
        std::fs::write(workspace.join(RECOVERY_PUBLICATION_RECEIPT), bytes).unwrap();
        fixture
    }

    #[test]
    fn publication_receipt_versions_reconcile_without_changing_originals() {
        for version in [1, 2, 3] {
            for had_config in [false, true] {
                let (_temporary, project, workspace) =
                    publication_fixture_with_version(version, had_config);
                let original = recovery_snapshot(&project).unwrap();
                let receipt = std::fs::read(workspace.join(RECOVERY_PUBLICATION_RECEIPT)).unwrap();
                let _lock = RecoveryLock::acquire(&project).unwrap();
                assert_eq!(recovery_snapshot(&project).unwrap(), original);
                assert!(!project.join(RECOVERY_PUBLICATION).exists());
                assert_eq!(
                    std::fs::read(workspace.join(RECOVERY_PUBLICATION_RECEIPT)).unwrap(),
                    receipt
                );
            }
        }
    }

    #[test]
    fn only_v3_publication_stamps_leave_out_apple_double_entries() {
        let temporary = tempfile::tempdir().unwrap();
        let segments = temporary.path().join("segments");
        std::fs::create_dir(&segments).unwrap();
        std::fs::write(segments.join("raw.m4s"), b"original raw").unwrap();
        let modified = segments.metadata().unwrap().modified().unwrap();
        let versions = [
            RecoveryPublicationStampVersion::V1,
            RecoveryPublicationStampVersion::V2,
            RecoveryPublicationStampVersion::V3,
        ];
        let before = versions.map(|version| {
            recovery_publication_segments_stamp(&segments, version)
                .unwrap()
                .unwrap()
        });

        std::fs::write(segments.join("._raw.m4s"), b"\x00\x05\x16\x07").unwrap();
        let mut directory = std::fs::OpenOptions::new();
        directory.read(true);
        #[cfg(windows)]
        {
            use std::os::windows::fs::OpenOptionsExt;
            const FILE_WRITE_ATTRIBUTES: u32 = 0x0100;
            const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
            directory
                .access_mode(FILE_WRITE_ATTRIBUTES)
                .custom_flags(FILE_FLAG_BACKUP_SEMANTICS);
        }
        directory
            .open(&segments)
            .unwrap()
            .set_times(std::fs::FileTimes::new().set_modified(modified))
            .unwrap();
        let after = versions.map(|version| {
            recovery_publication_segments_stamp(&segments, version)
                .unwrap()
                .unwrap()
        });

        assert_ne!(before[0], after[0]);
        assert_ne!(before[1], after[1]);
        assert_eq!(before[2], after[2]);
    }

    #[test]
    fn publication_receipts_reconcile_with_apple_double_entries_present() {
        for version in [1, 2, 3] {
            let (_temporary, project, workspace) =
                publication_fixture_with_receipt(version, true, true);
            let original = recovery_snapshot(&project).unwrap();
            let receipt = std::fs::read(workspace.join(RECOVERY_PUBLICATION_RECEIPT)).unwrap();
            let _lock = RecoveryLock::acquire(&project).unwrap();
            assert_eq!(recovery_snapshot(&project).unwrap(), original);
            assert!(!project.join(RECOVERY_PUBLICATION).exists());
            assert_eq!(
                std::fs::read(workspace.join(RECOVERY_PUBLICATION_RECEIPT)).unwrap(),
                receipt
            );
        }
    }

    #[test]
    fn publication_receipt_versions_retain_conflict_guards() {
        use std::io::Write;

        for version in [1, 2, 3] {
            for changed in [
                "raw", "added", "removed", "metadata", "config", "stamp", "receipt",
            ] {
                let (_temporary, project, workspace) =
                    publication_fixture_with_version(version, true);
                match changed {
                    "raw" => {
                        let path = project.join("content/segments/raw.m4s");
                        let modified = path.metadata().unwrap().modified().unwrap();
                        let mut file = std::fs::OpenOptions::new().write(true).open(path).unwrap();
                        file.set_len(0).unwrap();
                        file.write_all(b"different raw length with original modification time")
                            .unwrap();
                        file.set_times(std::fs::FileTimes::new().set_modified(modified))
                            .unwrap();
                    }
                    "added" => {
                        std::fs::create_dir(project.join("content/segments/unrelated")).unwrap();
                    }
                    "removed" => {
                        std::fs::remove_file(project.join("content/segments/raw.m4s")).unwrap();
                    }
                    "metadata" | "config" => {
                        let name = if changed == "metadata" {
                            "recording-meta.json"
                        } else {
                            "project-config.json"
                        };
                        let path = project.join(name);
                        let mut bytes = std::fs::read(&path).unwrap();
                        bytes[0] ^= 1;
                        std::fs::write(path, bytes).unwrap();
                    }
                    "stamp" => {
                        let path = project.join(RECOVERY_PUBLICATION);
                        let mut receipt: RecoveryPublication =
                            serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
                        receipt.original.segments.as_mut().unwrap()[0] ^= 1;
                        let bytes = serde_json::to_vec(&receipt).unwrap();
                        std::fs::write(path, &bytes).unwrap();
                        std::fs::write(workspace.join(RECOVERY_PUBLICATION_RECEIPT), bytes)
                            .unwrap();
                    }
                    "receipt" => {
                        std::fs::write(
                            workspace.join(RECOVERY_PUBLICATION_RECEIPT),
                            b"different receipt",
                        )
                        .unwrap();
                    }
                    _ => unreachable!(),
                }
                let before = recovery_snapshot(&project).unwrap();
                assert!(RecoveryLock::acquire(&project).is_err());
                assert_eq!(recovery_snapshot(&project).unwrap(), before);
                assert!(project.join(RECOVERY_PUBLICATION).is_file());
                assert!(workspace.join(RECOVERY_PUBLICATION_RECEIPT).is_file());
            }
        }
    }

    #[cfg(unix)]
    #[test]
    fn legacy_publication_receipts_never_fall_back_to_version_two_stamps() {
        let (_temporary, project, workspace) = publication_fixture_with_version(2, true);
        let legacy =
            recovery_publication_state_for_version(&project, RecoveryPublicationStampVersion::V1)
                .unwrap();
        let path = project.join(RECOVERY_PUBLICATION);
        let mut receipt: RecoveryPublication =
            serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
        assert!(legacy.segments != receipt.original.segments);
        receipt.version = 1;
        let bytes = serde_json::to_vec(&receipt).unwrap();
        std::fs::write(&path, &bytes).unwrap();
        std::fs::write(workspace.join(RECOVERY_PUBLICATION_RECEIPT), &bytes).unwrap();
        let before = recovery_snapshot(&project).unwrap();
        assert!(RecoveryLock::acquire(&project).is_err());
        assert_eq!(recovery_snapshot(&project).unwrap(), before);
        assert_eq!(std::fs::read(path).unwrap(), bytes);
    }

    fn scannable_publication_fixture() -> (tempfile::TempDir, PathBuf, PathBuf) {
        let (temporary, project, workspace) = publication_fixture();
        let meta = RecordingMeta {
            platform: None,
            project_path: project.clone(),
            pretty_name: "Interrupted publication".into(),
            sharing: None,
            upload: None,
            inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
                inner: MultipleSegments {
                    segments: Vec::new(),
                    cursors: Cursors::default(),
                    status: Some(StudioRecordingStatus::NeedsRemux),
                },
            })),
        };
        meta.save_for_project().unwrap();
        let display = project.join("content/segments/segment-0/display");
        std::fs::create_dir_all(&display).unwrap();
        std::fs::write(display.join("init.mp4"), [0; 128]).unwrap();
        let mut fragment = Vec::new();
        for kind in [b"moof", b"mdat"] {
            fragment.extend_from_slice(&72_u32.to_be_bytes());
            fragment.extend_from_slice(kind);
            fragment.extend_from_slice(&[0; 64]);
        }
        std::fs::write(display.join("segment_001.m4s"), fragment).unwrap();
        let staged_segment = workspace.join("staged/content/segments/segment-0");
        std::fs::create_dir_all(&staged_segment).unwrap();
        copy_recovery_input(&display, &staged_segment.join("display")).unwrap();
        (temporary, project, workspace)
    }

    fn interrupt_publication_rollback(
        project: &Path,
        workspace: &Path,
        failure: usize,
        interruption: usize,
        before_rename: bool,
    ) {
        let _lock = RecoveryLock::acquire(project).unwrap();
        let mut calls = 0;
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            publish_recovery_with(project, workspace, |source, destination| {
                calls += 1;
                if calls == failure {
                    return Err(std::io::Error::other("injected publication rename failure"));
                }
                assert!(
                    !before_rename || calls != interruption,
                    "interrupted before rollback rename"
                );
                std::fs::rename(source, destination)?;
                assert!(
                    before_rename || calls != interruption,
                    "interrupted after rollback rename"
                );
                Ok(())
            })
        }));
        assert!(result.is_err());
        assert_eq!(calls, interruption);
        assert!(project.join(RECOVERY_PUBLICATION).is_file());
    }

    #[test]
    fn interrupted_rollback_reconciles_and_relaunches_at_every_rename_boundary() {
        for had_config in [false, true] {
            for failure in 2..=4 {
                let last_rollback = match failure {
                    2 => 3,
                    3 => 5,
                    4 if had_config => 7,
                    4 => 6,
                    _ => unreachable!(),
                };
                for interruption in (failure + 1)..=last_rollback {
                    for before_rename in [false, true] {
                        let (temporary, project, workspace) = scannable_publication_fixture();
                        if !had_config {
                            std::fs::remove_file(project.join("project-config.json")).unwrap();
                        }
                        let original = recovery_snapshot(&project).unwrap();
                        let original_state = recovery_publication_state(&project).unwrap();
                        let staged_state =
                            recovery_publication_state(&workspace.join("staged")).unwrap();
                        interrupt_publication_rollback(
                            &project,
                            &workspace,
                            failure,
                            interruption,
                            before_rename,
                        );
                        let lock = RecoveryLock::acquire(&project).unwrap();
                        let current = recovery_publication_state(&project).unwrap();
                        assert_eq!(current.meta, original_state.meta);
                        assert!(
                            current.segments == original_state.segments
                                || current.segments == staged_state.segments
                        );
                        let raw = if project.join("content/segments/raw.m4s").is_file() {
                            project.join("content/segments")
                        } else {
                            workspace.join("original-segments")
                        };
                        for (path, bytes) in &original {
                            if let (Ok(relative), Some(bytes)) =
                                (path.strip_prefix("content/segments"), bytes)
                            {
                                let actual_digest =
                                    blake3::hash(&std::fs::read(raw.join(relative)).unwrap())
                                        .as_bytes()
                                        .to_vec();
                                assert_eq!(&actual_digest, bytes);
                            }
                        }
                        assert!(!project.join(RECOVERY_PUBLICATION).exists());
                        assert!(workspace.join(RECOVERY_PUBLICATION_RECEIPT).is_file());
                        drop(lock);
                        let before_scan = recovery_snapshot(&project).unwrap();
                        let found = RecoveryManager::find_incomplete(temporary.path());
                        assert_eq!(found.len(), 1);
                        assert!(matches!(
                            found[0].meta.studio_meta().unwrap().status(),
                            StudioRecordingStatus::NeedsRemux
                        ));
                        assert_eq!(recovery_snapshot(&project).unwrap(), before_scan);
                        let _lock = RecoveryLock::acquire(&project).unwrap();
                        assert_eq!(recovery_snapshot(&project).unwrap(), before_scan);
                    }
                }
            }
        }
    }

    #[test]
    fn fully_restored_rollback_finishes_its_journal_without_changing_originals() {
        for had_config in [false, true] {
            let (temporary, project, workspace) = scannable_publication_fixture();
            if !had_config {
                std::fs::remove_file(project.join("project-config.json")).unwrap();
            }
            let original = recovery_snapshot(&project).unwrap();
            interrupt_publication_rollback(
                &project,
                &workspace,
                4,
                if had_config { 7 } else { 6 },
                false,
            );
            assert_eq!(recovery_snapshot(&project).unwrap(), original);
            assert!(!workspace.join("original-segments").exists());
            assert!(!workspace.join("original-project-config.json").exists());
            assert!(!workspace.join("staged/project-config.json").exists());
            assert_eq!(RecoveryManager::find_incomplete(temporary.path()).len(), 1);
            assert_eq!(recovery_snapshot(&project).unwrap(), original);
            assert!(!project.join(RECOVERY_PUBLICATION).exists());
            assert!(workspace.join(RECOVERY_PUBLICATION_RECEIPT).is_file());
            assert!(RecoveryManager::inspect_recording(&project).is_some());
            assert!(RecoveryManager::find_incomplete_single(&project).is_some());
            assert_eq!(recovery_snapshot(&project).unwrap(), original);
        }
    }

    #[test]
    fn rollback_layout_still_refuses_conflicts_and_changed_generation_evidence() {
        for had_config in [false, true] {
            for changed in ["canonical", "metadata", "config", "staged", "receipt"] {
                let (temporary, project, workspace) = scannable_publication_fixture();
                if !had_config {
                    std::fs::remove_file(project.join("project-config.json")).unwrap();
                }
                interrupt_publication_rollback(
                    &project,
                    &workspace,
                    4,
                    if had_config { 6 } else { 5 },
                    false,
                );
                match changed {
                    "canonical" => {
                        std::fs::create_dir(project.join("content/segments")).unwrap();
                        std::fs::write(project.join("content/segments/unrelated"), b"unrelated")
                            .unwrap();
                    }
                    "metadata" => {
                        let mut meta = RecordingMeta::load_for_project(&project).unwrap();
                        meta.pretty_name = "Different recording generation".into();
                        meta.save_for_project().unwrap();
                    }
                    "config" => std::fs::write(
                        project.join("project-config.json"),
                        b"different configuration",
                    )
                    .unwrap(),
                    "staged" => std::fs::write(
                        workspace.join("staged/content/segments/display.mp4"),
                        b"different staged data",
                    )
                    .unwrap(),
                    "receipt" => std::fs::write(
                        workspace.join(RECOVERY_PUBLICATION_RECEIPT),
                        b"different receipt",
                    )
                    .unwrap(),
                    _ => unreachable!(),
                }
                let before = recovery_snapshot(&project).unwrap();
                assert!(RecoveryLock::acquire(&project).is_err());
                assert!(RecoveryManager::find_incomplete(temporary.path()).is_empty());
                assert_eq!(recovery_snapshot(&project).unwrap(), before);
                assert_eq!(
                    std::fs::read(workspace.join("original-segments/raw.m4s")).unwrap(),
                    b"original raw"
                );
                assert!(project.join(RECOVERY_PUBLICATION).is_file());
                assert!(matches!(
                    RecordingMeta::load_for_project(&project)
                        .unwrap()
                        .studio_meta()
                        .unwrap()
                        .status(),
                    StudioRecordingStatus::NeedsRemux
                ));
            }
        }
    }

    #[test]
    fn interrupted_publication_reconciles_every_completed_rename_without_inventing_status() {
        for after in 0..=4 {
            let (_temporary, project, workspace) = publication_fixture();
            let original = recovery_snapshot(&project).unwrap();
            interrupt_publication(&project, &workspace, after);
            let _lock = RecoveryLock::acquire(&project).unwrap();
            assert!(!project.join(RECOVERY_PUBLICATION).exists());
            assert!(workspace.join(RECOVERY_PUBLICATION_RECEIPT).is_file());
            if after <= 1 {
                assert_eq!(recovery_snapshot(&project).unwrap(), original);
            } else {
                assert_eq!(
                    std::fs::read(project.join("content/segments/display.mp4")).unwrap(),
                    b"validated output"
                );
                assert_eq!(
                    std::fs::read(workspace.join("original-segments/raw.m4s")).unwrap(),
                    b"original raw"
                );
            }
            assert_eq!(
                std::fs::read(project.join("recording-meta.json")).unwrap(),
                if after < 4 {
                    &b"original status"[..]
                } else {
                    &b"complete"[..]
                }
            );
        }
    }

    #[test]
    fn relaunch_scan_restores_first_rename_and_keeps_recording_recoverable() {
        let (temporary, project, workspace) = scannable_publication_fixture();
        let original = recovery_snapshot(&project).unwrap();
        interrupt_publication(&project, &workspace, 1);
        assert!(!project.join("content/segments").exists());
        let found = RecoveryManager::find_incomplete(temporary.path());
        assert_eq!(found.len(), 1);
        assert_eq!(found[0].project_path, project);
        assert!(matches!(
            found[0].meta.studio_meta().unwrap().status(),
            StudioRecordingStatus::NeedsRemux
        ));
        assert_eq!(recovery_snapshot(&project).unwrap(), original);
        assert!(RecoveryManager::inspect_recording(&project).is_some());
        assert!(RecoveryManager::find_incomplete_single(&project).is_some());
    }

    #[test]
    fn relaunch_after_segments_install_retains_canonical_data_and_original_status() {
        for after in [2, 3] {
            let (temporary, project, workspace) = scannable_publication_fixture();
            let original_meta = std::fs::read(project.join("recording-meta.json")).unwrap();
            interrupt_publication(&project, &workspace, after);
            let before_scan = recovery_snapshot(&project).unwrap();
            assert_eq!(RecoveryManager::find_incomplete(temporary.path()).len(), 1);
            assert_eq!(recovery_snapshot(&project).unwrap(), before_scan);
            assert_eq!(
                std::fs::read(project.join("recording-meta.json")).unwrap(),
                original_meta
            );
            assert!(workspace.join("original-segments/raw.m4s").is_file());
            assert!(workspace.join(RECOVERY_PUBLICATION_RECEIPT).is_file());
        }
    }

    #[test]
    fn interrupted_restoration_is_idempotent_and_receipt_generation_must_match() {
        let (_temporary, project, workspace) = publication_fixture();
        let original = recovery_snapshot(&project).unwrap();
        interrupt_publication(&project, &workspace, 1);
        std::fs::rename(
            workspace.join("original-segments"),
            project.join("content/segments"),
        )
        .unwrap();
        let receipt = workspace.join(RECOVERY_PUBLICATION_RECEIPT);
        let bytes = std::fs::read(&receipt).unwrap();
        std::fs::write(&receipt, b"different generation").unwrap();
        assert!(RecoveryLock::acquire(&project).is_err());
        assert_eq!(recovery_snapshot(&project).unwrap(), original);
        assert!(project.join(RECOVERY_PUBLICATION).is_file());
        std::fs::write(receipt, bytes).unwrap();
        let _lock = RecoveryLock::acquire(&project).unwrap();
        assert_eq!(recovery_snapshot(&project).unwrap(), original);
        assert!(!project.join(RECOVERY_PUBLICATION).exists());
    }

    #[test]
    fn interrupted_publication_without_original_config_preserves_that_state() {
        for after in 0..=3 {
            let (_temporary, project, workspace) = publication_fixture();
            std::fs::remove_file(project.join("project-config.json")).unwrap();
            interrupt_publication(&project, &workspace, after);
            let _lock = RecoveryLock::acquire(&project).unwrap();
            assert_eq!(project.join("project-config.json").exists(), after == 3);
            assert_eq!(
                std::fs::read(project.join("recording-meta.json")).unwrap(),
                b"original status"
            );
        }
    }

    #[test]
    fn interrupted_publication_never_overwrites_conflicting_canonical_segments() {
        for conflicting_file in [false, true] {
            let (_temporary, project, workspace) = publication_fixture();
            interrupt_publication(&project, &workspace, 1);
            std::fs::create_dir(project.join("content/segments")).unwrap();
            if conflicting_file {
                std::fs::write(project.join("content/segments/unrelated"), b"unrelated").unwrap();
            }
            let before = recovery_snapshot(&project).unwrap();
            assert!(RecoveryLock::acquire(&project).is_err());
            assert_eq!(recovery_snapshot(&project).unwrap(), before);
            assert_eq!(
                std::fs::read(workspace.join("original-segments/raw.m4s")).unwrap(),
                b"original raw"
            );
            assert!(project.join(RECOVERY_PUBLICATION).is_file());
        }
    }

    #[test]
    fn stale_publication_metadata_or_tree_keeps_evidence_and_does_not_mark_failed() {
        for changed in ["recording-meta.json", "original-segments/raw.m4s"] {
            let (temporary, project, workspace) = scannable_publication_fixture();
            interrupt_publication(&project, &workspace, 1);
            let target = if changed == "recording-meta.json" {
                let mut meta = RecordingMeta::load_for_project(&project).unwrap();
                meta.pretty_name = "A later recording generation".into();
                meta.save_for_project().unwrap();
                project.join(changed)
            } else {
                let target = workspace.join(changed);
                std::fs::write(&target, b"changed raw bytes").unwrap();
                target
            };
            let bytes = std::fs::read(&target).unwrap();
            assert!(RecoveryLock::acquire(&project).is_err());
            assert!(RecoveryManager::find_incomplete(temporary.path()).is_empty());
            assert_eq!(std::fs::read(target).unwrap(), bytes);
            assert!(matches!(
                RecordingMeta::load_for_project(&project)
                    .unwrap()
                    .studio_meta()
                    .unwrap()
                    .status(),
                StudioRecordingStatus::NeedsRemux
            ));
            assert!(!project.join("content/segments").exists());
            assert!(project.join(RECOVERY_PUBLICATION).is_file());
        }
    }

    #[test]
    fn invalid_or_wrong_generation_receipts_cannot_select_a_workspace() {
        for value in [
            "invalid-json",
            "version",
            "generation",
            "project",
            "escape",
            "oversized",
        ] {
            let (_temporary, project, workspace) = publication_fixture();
            interrupt_publication(&project, &workspace, 1);
            let path = project.join(RECOVERY_PUBLICATION);
            let mut receipt: RecoveryPublication =
                serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
            let bytes = match value {
                "invalid-json" => b"{".to_vec(),
                "oversized" => vec![0; RECOVERY_PUBLICATION_MAX_BYTES as usize + 1],
                _ => {
                    match value {
                        "version" => receipt.version = u32::MAX,
                        "generation" => {
                            receipt.workspace = format!(".recovery-{}", uuid::Uuid::new_v4())
                        }
                        "project" => receipt.project = project.join("other"),
                        "escape" => receipt.workspace = "../outside".into(),
                        _ => unreachable!(),
                    }
                    serde_json::to_vec(&receipt).unwrap()
                }
            };
            std::fs::write(&path, &bytes).unwrap();
            assert!(RecoveryLock::acquire(&project).is_err());
            assert_eq!(std::fs::read(path).unwrap(), bytes);
            assert_eq!(
                std::fs::read(workspace.join("original-segments/raw.m4s")).unwrap(),
                b"original raw"
            );
            assert!(!project.join("content/segments").exists());
        }
    }

    #[test]
    fn legacy_workspaces_without_receipts_are_not_guessed_or_deleted() {
        let (temporary, project, workspace) = scannable_publication_fixture();
        assert_eq!(RecoveryManager::find_incomplete(temporary.path()).len(), 1);
        std::fs::rename(
            project.join("content/segments"),
            workspace.join("original-segments"),
        )
        .unwrap();
        let original_meta = std::fs::read(project.join("recording-meta.json")).unwrap();
        assert!(RecoveryManager::find_incomplete(temporary.path()).is_empty());
        assert_eq!(
            std::fs::read(project.join("recording-meta.json")).unwrap(),
            original_meta
        );
        assert!(workspace.join("original-segments/raw.m4s").is_file());
    }

    #[cfg(unix)]
    #[test]
    fn publication_reconciliation_refuses_symlinked_receipts_and_workspace_entries() {
        use std::os::unix::fs::symlink;
        for target in ["receipt", "workspace", "segments", "metadata", "content"] {
            let (temporary, project, workspace) = publication_fixture();
            interrupt_publication(&project, &workspace, 1);
            let source = match target {
                "receipt" => project.join(RECOVERY_PUBLICATION),
                "workspace" => workspace.clone(),
                "segments" => workspace.join("original-segments"),
                "metadata" => workspace.join("original-recording-meta.json"),
                "content" => project.join("content"),
                _ => unreachable!(),
            };
            let outside = temporary.path().join("outside");
            std::fs::rename(&source, &outside).unwrap();
            symlink(&outside, &source).unwrap();
            assert!(RecoveryLock::acquire(&project).is_err());
            assert!(source.symlink_metadata().unwrap().file_type().is_symlink());
            assert!(outside.exists());
        }
    }

    #[test]
    fn recovery_publication_rolls_back_each_failed_rename() {
        for failure in 1..=4 {
            let (_temporary, project, workspace) = publication_fixture();
            let before = recovery_snapshot(&project).unwrap();
            let mut calls = 0;
            let result = publish_recovery_with(&project, &workspace, |source, destination| {
                calls += 1;
                if calls == failure {
                    return Err(std::io::Error::other("injected publication failure"));
                }
                std::fs::rename(source, destination)
            });
            assert!(result.is_err());
            assert_eq!(recovery_snapshot(&project).unwrap(), before);
            assert_eq!(
                std::fs::read(project.join("recording-meta.json")).unwrap(),
                b"original status"
            );
        }
    }

    #[test]
    fn preparing_reader_retains_recovery_lock_after_source_and_finalizer_drop() {
        let (_temporary, project, workspace) = publication_fixture();
        let mut reader = {
            let lock = Arc::new(RecoveryLock::acquire(&project).unwrap());
            let source =
                RelocatableSource::new_with_owner(project.join("content/segments"), lock.clone())
                    .unwrap();
            let mut reader = source.reader(Path::new("raw.m4s")).unwrap();
            let mut prefix = [0; 4];
            reader.read_exact(&mut prefix).unwrap();
            assert_eq!(&prefix, b"orig");
            publish_recovery_with_source(&project, &workspace, &source).unwrap();
            reader
        };
        assert!(RecoveryLock::acquire(&project).is_err());
        let mut suffix = Vec::new();
        reader.read_to_end(&mut suffix).unwrap();
        assert_eq!(suffix, b"inal raw");
        drop(reader);
        let lock = RecoveryLock::acquire(&project).unwrap();
        drop(lock);
    }

    #[test]
    fn preparing_source_failures_release_recovery_lock_without_retained_readers() {
        let (_temporary, project, _workspace) = publication_fixture();
        let owner = Arc::new(RecoveryLock::acquire(&project).unwrap());
        assert!(RelocatableSource::new_with_owner(project.join("missing"), owner).is_err());
        let owner = Arc::new(RecoveryLock::acquire(&project).unwrap());
        let source =
            RelocatableSource::new_with_owner(project.join("content/segments"), owner).unwrap();
        assert!(source.reader(Path::new("missing.m4s")).is_err());
        drop(source);
        let lock = RecoveryLock::acquire(&project).unwrap();
        drop(lock);
    }

    #[test]
    fn managed_recovery_publication_keeps_readers_on_original_media() {
        let (_temporary, project, workspace) = publication_fixture();
        let source = RelocatableSource::new(project.join("content/segments")).unwrap();
        let mut reader = source.reader(Path::new("raw.m4s")).unwrap();
        let mut prefix = [0; 4];
        reader.read_exact(&mut prefix).unwrap();
        assert_eq!(&prefix, b"orig");
        publish_recovery_with_source(&project, &workspace, &source).unwrap();
        let mut suffix = Vec::new();
        reader.read_to_end(&mut suffix).unwrap();
        assert_eq!(suffix, b"inal raw");
        reader.seek(SeekFrom::Start(0)).unwrap();
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).unwrap();
        assert_eq!(bytes, b"original raw");
        let mut reopened = source.reader(Path::new("raw.m4s")).unwrap();
        bytes.clear();
        reopened.read_to_end(&mut bytes).unwrap();
        assert_eq!(bytes, b"original raw");
        assert_eq!(
            std::fs::read(project.join("content/segments/display.mp4")).unwrap(),
            b"validated output"
        );
        assert!(!project.join(RECOVERY_PUBLICATION).exists());
    }

    #[test]
    fn managed_recovery_readers_survive_every_publication_rollback() {
        for failure in 1..=4 {
            let (_temporary, project, workspace) = publication_fixture();
            let before = recovery_snapshot(&project).unwrap();
            let original = project.join("content/segments");
            let backup = workspace.join("original-segments");
            let source = RelocatableSource::new(original.clone()).unwrap();
            let mut reader = source.reader(Path::new("raw.m4s")).unwrap();
            let mut prefix = [0; 4];
            reader.read_exact(&mut prefix).unwrap();
            let mut calls = 0;
            let result = publish_recovery_with(&project, &workspace, |from, to| {
                calls += 1;
                if calls == failure {
                    return Err(std::io::Error::other(
                        "injected managed publication failure",
                    ));
                }
                rename_recovery_path_with_source(from, to, &original, &backup, &source)
            });
            assert!(result.is_err());
            assert_eq!(recovery_snapshot(&project).unwrap(), before);
            assert!(!project.join(RECOVERY_PUBLICATION).exists());
            let mut suffix = Vec::new();
            reader.read_to_end(&mut suffix).unwrap();
            assert_eq!(suffix, b"inal raw");
            assert!(source.reader(Path::new("raw.m4s")).is_ok());
        }
    }

    #[test]
    fn managed_recovery_rollback_failure_retains_readable_originals() {
        for rollback_failure in 5..=7 {
            let (_temporary, project, workspace) = publication_fixture();
            let original = project.join("content/segments");
            let backup = workspace.join("original-segments");
            let source = RelocatableSource::new(original.clone()).unwrap();
            let mut reader = source.reader(Path::new("raw.m4s")).unwrap();
            let mut prefix = [0; 4];
            reader.read_exact(&mut prefix).unwrap();
            let mut calls = 0;
            let result = publish_recovery_with(&project, &workspace, |from, to| {
                calls += 1;
                if calls == 4 || calls == rollback_failure {
                    return Err(std::io::Error::other("injected managed rollback failure"));
                }
                rename_recovery_path_with_source(from, to, &original, &backup, &source)
            });
            assert!(result.unwrap_err().to_string().contains("rollback failed"));
            assert!(project.join(RECOVERY_PUBLICATION).is_file());
            assert_eq!(
                std::fs::read(backup.join("raw.m4s")).unwrap(),
                b"original raw"
            );
            let mut suffix = Vec::new();
            reader.read_to_end(&mut suffix).unwrap();
            assert_eq!(suffix, b"inal raw");
        }
    }

    #[test]
    fn managed_recovery_refuses_a_different_projects_source() {
        let (_temporary, project, workspace) = publication_fixture();
        let (_other_temporary, other, _other_workspace) = publication_fixture();
        let before = recovery_snapshot(&project).unwrap();
        let other_before = recovery_snapshot(&other).unwrap();
        let source = RelocatableSource::new(other.join("content/segments")).unwrap();
        let mut reader = source.reader(Path::new("raw.m4s")).unwrap();
        assert!(publish_recovery_with_source(&project, &workspace, &source).is_err());
        assert_eq!(recovery_snapshot(&project).unwrap(), before);
        assert_eq!(recovery_snapshot(&other).unwrap(), other_before);
        assert!(!project.join(RECOVERY_PUBLICATION).exists());
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).unwrap();
        assert_eq!(bytes, b"original raw");
    }

    #[test]
    fn managed_recovery_lock_leaves_pending_publication_for_reader_shutdown() {
        let (_temporary, project, workspace) = publication_fixture();
        let original = project.join("content/segments");
        let backup = workspace.join("original-segments");
        let source = RelocatableSource::new(original.clone()).unwrap();
        let mut reader = source.reader(Path::new("raw.m4s")).unwrap();
        let mut prefix = [0; 4];
        reader.read_exact(&mut prefix).unwrap();
        {
            let _lock = RecoveryLock::acquire(&project).unwrap();
            let mut calls = 0;
            let interrupted = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                publish_recovery_with(&project, &workspace, |from, to| {
                    rename_recovery_path_with_source(from, to, &original, &backup, &source)?;
                    calls += 1;
                    assert_ne!(calls, 1, "interrupted after managed source relocation");
                    Ok(())
                })
            }));
            assert!(interrupted.is_err());
        }
        let receipt = std::fs::read(project.join(RECOVERY_PUBLICATION)).unwrap();
        assert!(RecoveryLock::acquire_for_preparing_preview(&project).is_err());
        assert_eq!(
            std::fs::read(project.join(RECOVERY_PUBLICATION)).unwrap(),
            receipt
        );
        assert!(!original.exists());
        assert_eq!(
            std::fs::read(backup.join("raw.m4s")).unwrap(),
            b"original raw"
        );
        let mut suffix = Vec::new();
        reader.read_to_end(&mut suffix).unwrap();
        assert_eq!(suffix, b"inal raw");
        drop(reader);
        drop(source);
        let _lock = RecoveryLock::acquire(&project).unwrap();
        assert_eq!(
            std::fs::read(original.join("raw.m4s")).unwrap(),
            b"original raw"
        );
        assert!(!project.join(RECOVERY_PUBLICATION).exists());
    }

    #[test]
    fn recovery_scan_cannot_mark_failed_during_publication_rollback() {
        let (temporary, project, workspace) = publication_fixture();
        let meta = RecordingMeta {
            platform: None,
            project_path: project.clone(),
            pretty_name: "Publication scan race".into(),
            sharing: None,
            upload: None,
            inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
                inner: MultipleSegments {
                    segments: Vec::new(),
                    cursors: Cursors::default(),
                    status: Some(StudioRecordingStatus::NeedsRemux),
                },
            })),
        };
        meta.save_for_project().unwrap();
        let before = recovery_snapshot(&project).unwrap();
        let _lock = RecoveryLock::acquire(&project).unwrap();
        let mut calls = 0;
        let result = publish_recovery_with(&project, &workspace, |source, destination| {
            calls += 1;
            if calls == 2 {
                assert!(!project.join("content/segments").exists());
                assert!(RecoveryManager::find_incomplete(temporary.path()).is_empty());
                return Err(std::io::Error::other("injected install failure after scan"));
            }
            std::fs::rename(source, destination)
        });
        assert!(result.is_err());
        assert_eq!(recovery_snapshot(&project).unwrap(), before);
        let meta = RecordingMeta::load_for_project(&project).unwrap();
        assert!(matches!(
            meta.studio_meta().unwrap().status(),
            StudioRecordingStatus::NeedsRemux
        ));
    }

    #[test]
    fn recovery_rollback_failure_retains_original_raw_and_status() {
        let (_temporary, project, workspace) = publication_fixture();
        let mut calls = 0;
        let result = publish_recovery_with(&project, &workspace, |source, destination| {
            calls += 1;
            if calls == 4 || calls == 6 {
                return Err(std::io::Error::other(
                    "injected rename and rollback failure",
                ));
            }
            std::fs::rename(source, destination)
        });
        assert!(result.unwrap_err().to_string().contains("rollback failed"));
        assert_eq!(
            std::fs::read(workspace.join("original-segments/raw.m4s")).unwrap(),
            b"original raw"
        );
        assert_eq!(
            std::fs::read(project.join("recording-meta.json")).unwrap(),
            b"original status"
        );
        assert_eq!(
            std::fs::read(workspace.join("original-recording-meta.json")).unwrap(),
            b"original status"
        );
    }

    #[test]
    fn recovery_publication_commits_metadata_last_and_retains_backup_until_success() {
        let (_temporary, project, workspace) = publication_fixture();
        let mut calls = 0;
        publish_recovery_with(&project, &workspace, |source, destination| {
            calls += 1;
            assert_eq!(
                std::fs::read(project.join("recording-meta.json")).unwrap(),
                b"original status"
            );
            if calls > 1 {
                assert_eq!(
                    std::fs::read(workspace.join("original-segments/raw.m4s")).unwrap(),
                    b"original raw"
                );
            }
            if calls == 4 {
                assert_eq!(destination, project.join("recording-meta.json"));
            }
            std::fs::rename(source, destination)
        })
        .unwrap();
        assert_eq!(calls, 4);
        assert_eq!(
            std::fs::read(project.join("recording-meta.json")).unwrap(),
            b"complete"
        );
        assert!(workspace.join("original-segments/raw.m4s").is_file());
        assert!(project.join("content/segments/display.mp4").is_file());
    }

    #[test]
    fn recovery_copy_refuses_existing_destination_and_preserves_source() {
        let dir = tempfile::tempdir().unwrap();
        let source = dir.path().join("raw");
        let destination = dir.path().join("occupied");
        std::fs::write(&source, b"original").unwrap();
        std::fs::write(&destination, b"existing").unwrap();
        for durability in [
            RecoveryCopyDurability::Durable,
            RecoveryCopyDurability::Deferred,
        ] {
            assert!(
                copy_recovery_input_with_durability(&source, &destination, durability).is_err()
            );
            assert_eq!(std::fs::read(&source).unwrap(), b"original");
            assert_eq!(std::fs::read(&destination).unwrap(), b"existing");
        }
    }

    #[test]
    fn recovery_copies_and_snapshots_skip_apple_double_siblings() {
        let dir = tempfile::tempdir().unwrap();
        let project = dir.path().join("project");
        let segment = project.join("content/segments/segment-0");
        std::fs::create_dir_all(&segment).unwrap();
        std::fs::write(segment.join("display.mp4"), b"media").unwrap();
        let before = recovery_snapshot(&project).unwrap();

        let apple_double = b"\x00\x05\x16\x07";
        std::fs::write(segment.join("._display.mp4"), apple_double).unwrap();
        std::fs::write(project.join("content/segments/._segment-0"), apple_double).unwrap();
        assert_eq!(recovery_snapshot(&project).unwrap(), before);

        let staged = dir.path().join("staged");
        copy_recovery_input(&project.join("content"), &staged).unwrap();
        assert_eq!(
            std::fs::read(staged.join("segments/segment-0/display.mp4")).unwrap(),
            b"media"
        );
        for companion in ["segments/segment-0/._display.mp4", "segments/._segment-0"] {
            assert_ne!(
                std::fs::read(staged.join(companion)).ok().as_deref(),
                Some(&apple_double[..])
            );
        }
    }

    #[test]
    fn recovery_lock_refuses_concurrent_attempt_without_touching_first_lock() {
        let dir = tempfile::tempdir().unwrap();
        let lock = RecoveryLock::acquire(dir.path()).unwrap();
        assert!(RecoveryLock::acquire(dir.path()).is_err());
        assert!(dir.path().join(".recovery.lock").exists());
        drop(lock);
        assert!(dir.path().join(".recovery.lock").exists());
        let reacquired = RecoveryLock::acquire(dir.path()).unwrap();
        drop(reacquired);
    }

    #[cfg(unix)]
    #[test]
    fn recovery_lock_release_does_not_wait_for_inherited_descriptor() {
        let dir = tempfile::tempdir().unwrap();
        let lock = RecoveryLock::acquire(dir.path()).unwrap();
        let inherited = lock._file.try_clone().unwrap();
        assert!(RecoveryLock::acquire(dir.path()).is_err());
        drop(lock);
        let reacquired = RecoveryLock::acquire(dir.path()).unwrap();
        drop(inherited);
        assert!(RecoveryLock::acquire(dir.path()).is_err());
        drop(reacquired);
        assert!(RecoveryLock::acquire(dir.path()).is_ok());
    }

    #[cfg(unix)]
    #[test]
    fn recovery_lock_inherited_guard_drop_does_not_unlock_parent() {
        fn reap_child(pid: libc::pid_t) -> std::io::Result<Option<i32>> {
            let deadline = std::time::Instant::now() + Duration::from_secs(5);
            loop {
                let mut status = 0;
                match unsafe { libc::waitpid(pid, &mut status, libc::WNOHANG) } {
                    waited if waited == pid => return Ok(Some(status)),
                    -1 => {
                        let error = std::io::Error::last_os_error();
                        if error.kind() != std::io::ErrorKind::Interrupted {
                            return Err(error);
                        }
                    }
                    _ => {}
                }
                if std::time::Instant::now() >= deadline {
                    return Ok(None);
                }
                std::thread::sleep(Duration::from_millis(10));
            }
        }

        let dir = tempfile::tempdir().unwrap();
        let lock = RecoveryLock::acquire(dir.path()).unwrap();
        let pid = unsafe { libc::fork() };
        if pid == 0 {
            // Only async-signal-safe operations may run in a child forked from the test harness.
            drop(lock);
            unsafe { libc::_exit(0) };
        }
        assert!(pid >= 0, "fork failed: {}", std::io::Error::last_os_error());
        let status = match reap_child(pid).unwrap() {
            Some(status) => status,
            None => {
                let killed = unsafe { libc::kill(pid, libc::SIGKILL) };
                let reaped = reap_child(pid);
                panic!("Forked lock probe timed out: kill={killed}, reap={reaped:?}");
            }
        };
        assert!(libc::WIFEXITED(status));
        assert_eq!(libc::WEXITSTATUS(status), 0);
        assert!(RecoveryLock::acquire(dir.path()).is_err());
        drop(lock);
        assert!(RecoveryLock::acquire(dir.path()).is_ok());
    }

    #[test]
    fn recovery_manifest_paths_cannot_escape_the_track_directory() {
        let dir = Path::new("content/segments/segment-0/display");
        for name in [
            "",
            "../original.mp4",
            "/outside.mp4",
            "nested/../../outside.mp4",
        ] {
            assert!(recovery_child_path(dir, name).is_none());
        }
        assert_eq!(
            recovery_child_path(dir, "segment_0.m4s"),
            Some(dir.join("segment_0.m4s"))
        );
    }

    #[cfg(unix)]
    #[test]
    fn recovery_rejects_symlinks_and_creates_private_workspace() {
        use std::os::unix::fs::{PermissionsExt, symlink};
        let dir = tempfile::tempdir().unwrap();
        let outside = dir.path().join("outside");
        std::fs::write(&outside, b"outside").unwrap();
        let project = dir.path().join("project");
        create_private_recovery_dir(&project).unwrap();
        assert_eq!(
            std::fs::metadata(&project).unwrap().permissions().mode() & 0o777,
            0o700
        );
        symlink(&outside, project.join("content")).unwrap();
        assert!(recovery_snapshot(&project).is_err());
        assert!(copy_recovery_input(&project.join("content"), &project.join("copy")).is_err());
        assert_eq!(std::fs::read(&outside).unwrap(), b"outside");
    }

    fn large_recovery_project() -> (tempfile::TempDir, Vec<PathBuf>) {
        let dir = tempfile::tempdir().unwrap();
        let fragments = dir.path().join("content/segments/segment-0/display");
        std::fs::create_dir_all(&fragments).unwrap();
        std::fs::write(dir.path().join("recording-meta.json"), b"{}").unwrap();
        let mut seed = 0x9e37_79b9_u32;
        let files = (0..24)
            .map(|index| {
                let bytes: Vec<u8> = (0..2 * 1024 * 1024)
                    .map(|_| {
                        seed ^= seed << 13;
                        seed ^= seed >> 17;
                        seed ^= seed << 5;
                        seed as u8
                    })
                    .collect();
                let path = fragments.join(format!("segment_{index:03}.m4s"));
                std::fs::write(&path, bytes).unwrap();
                path
            })
            .collect();
        (dir, files)
    }

    #[test]
    fn parallel_recovery_snapshot_matches_sequential_hashes() {
        let (dir, fragments) = large_recovery_project();
        let snapshot = recovery_snapshot(dir.path()).unwrap();

        let mut files = fragments.clone();
        files.push(dir.path().join("recording-meta.json"));
        let sequential = hash_recovery_files(dir.path(), &files).unwrap();
        assert_eq!(
            hash_recovery_files_parallel(dir.path(), &files, 4).unwrap(),
            sequential
        );
        for (path, hash) in &sequential {
            assert_eq!(snapshot.get(path), Some(hash));
        }
        for fragment in &fragments {
            let relative = fragment.strip_prefix(dir.path()).unwrap();
            assert_eq!(
                snapshot.get(relative),
                Some(&Some(
                    blake3::hash(&std::fs::read(fragment).unwrap())
                        .as_bytes()
                        .to_vec()
                ))
            );
        }
        assert_eq!(snapshot.get(Path::new("content/segments")), Some(&None));
        assert_eq!(snapshot.len(), sequential.len() + 4);

        let last = fragments.last().unwrap();
        let mut bytes = std::fs::read(last).unwrap();
        bytes[1024] ^= 1;
        std::fs::write(last, bytes).unwrap();
        assert_ne!(recovery_snapshot(dir.path()).unwrap(), snapshot);
    }

    #[test]
    fn parallel_recovery_hashing_reports_unreadable_inputs() {
        let (dir, mut fragments) = large_recovery_project();
        fragments.insert(12, dir.path().join("content/missing.m4s"));
        assert!(hash_recovery_files_parallel(dir.path(), &fragments, 4).is_err());
        assert!(hash_recovery_files_parallel(dir.path(), &fragments, 1).is_err());
    }

    #[test]
    fn recovery_declared_complete_missing_or_corrupt_fragment_is_not_skipped() {
        let dir = tempfile::tempdir().unwrap();
        let manifest = dir.path().join("manifest.json");
        std::fs::write(
            &manifest,
            br#"{"fragments":[{"path":"missing.mp4","is_complete":true,"file_size":10}]}"#,
        )
        .unwrap();
        assert!(validate_recovery_manifests(dir.path()).is_err());
        std::fs::write(dir.path().join("missing.mp4"), b"short").unwrap();
        assert!(validate_recovery_manifests(dir.path()).is_err());
        std::fs::write(
            &manifest,
            br#"{"init_segment":"../outside.mp4","fragments":[]}"#,
        )
        .unwrap();
        assert!(validate_recovery_manifests(dir.path()).is_err());
    }

    #[test]
    fn recovery_source_snapshot_detects_bytes_and_whole_segment_changes() {
        let (_temporary, project, _workspace) = publication_fixture();
        let before = recovery_snapshot(&project).unwrap();
        let raw = project.join("content/segments/raw.m4s");
        let modified = std::fs::metadata(&raw).unwrap().modified().unwrap();
        std::fs::write(&raw, b"modified raw").unwrap();
        std::fs::OpenOptions::new()
            .write(true)
            .open(&raw)
            .unwrap()
            .set_times(std::fs::FileTimes::new().set_modified(modified))
            .unwrap();
        assert_eq!(
            std::fs::metadata(&raw).unwrap().modified().unwrap(),
            modified
        );
        assert_ne!(recovery_snapshot(&project).unwrap(), before);
        std::fs::write(project.join("content/segments/raw.m4s"), b"original raw").unwrap();
        assert_eq!(recovery_snapshot(&project).unwrap(), before);
        std::fs::create_dir(project.join("content/segments/segment-1")).unwrap();
        assert_ne!(recovery_snapshot(&project).unwrap(), before);
    }

    #[test]
    fn large_recovery_snapshots_preserve_exact_bytes_and_directory_entries() {
        use std::io::{Seek, SeekFrom, Write};

        let directory = tempfile::tempdir().unwrap();
        let project = directory.path();
        std::fs::create_dir_all(project.join("content/nested/empty")).unwrap();
        let first = vec![0x25; 16 * 1024 * 1024 + 1];
        let second = vec![0x82; first.len()];
        std::fs::write(project.join("content/first.bin"), &first).unwrap();
        std::fs::write(project.join("content/nested/second.bin"), &second).unwrap();
        std::fs::write(project.join("recording-meta.json"), b"metadata").unwrap();
        std::fs::write(project.join("excluded"), b"not a recovery input").unwrap();

        let mut expected = RecoverySnapshot::new();
        for path in ["content", "content/nested", "content/nested/empty"] {
            let _ = expected.insert(PathBuf::from(path), None);
        }
        for (path, bytes) in [
            ("content/first.bin", first.as_slice()),
            ("content/nested/second.bin", second.as_slice()),
            ("recording-meta.json", b"metadata".as_slice()),
        ] {
            let _ = expected.insert(
                PathBuf::from(path),
                Some(blake3::hash(bytes).as_bytes().to_vec()),
            );
        }
        assert_eq!(recovery_snapshot(project).unwrap(), expected);

        let path = project.join("content/nested/second.bin");
        let modified = std::fs::metadata(&path).unwrap().modified().unwrap();
        let mut file = std::fs::OpenOptions::new().write(true).open(&path).unwrap();
        file.seek(SeekFrom::End(-1)).unwrap();
        file.write_all(&[0x83]).unwrap();
        file.set_times(std::fs::FileTimes::new().set_modified(modified))
            .unwrap();
        assert_ne!(recovery_snapshot(project).unwrap(), expected);
        file.seek(SeekFrom::End(-1)).unwrap();
        file.write_all(&[0x82]).unwrap();
        assert_eq!(recovery_snapshot(project).unwrap(), expected);
        std::fs::remove_dir(project.join("content/nested/empty")).unwrap();
        assert_ne!(recovery_snapshot(project).unwrap(), expected);
    }
    #[test]
    fn recovery_lock_child_probe() {
        let Some(path) = std::env::var_os("CAP_RECOVERY_LOCK_CHILD") else {
            return;
        };
        let project = PathBuf::from(path);
        let _lock = RecoveryLock::acquire(&project).unwrap();
        std::fs::write(project.join("child-ready"), b"ready").unwrap();
        std::thread::sleep(Duration::from_secs(10));
    }

    #[test]
    fn recovery_kernel_lock_releases_after_child_process_death() {
        struct Child(std::process::Child);
        impl Drop for Child {
            fn drop(&mut self) {
                let _ = self.0.kill();
                let _ = self.0.wait();
            }
        }
        let directory = tempfile::tempdir().unwrap();
        let mut child = Child(
            std::process::Command::new(std::env::current_exe().unwrap())
                .args([
                    "--exact",
                    "recovery::transactional_recovery_tests::recovery_lock_child_probe",
                    "--nocapture",
                ])
                .env("CAP_RECOVERY_LOCK_CHILD", directory.path())
                .stdout(std::process::Stdio::null())
                .spawn()
                .unwrap(),
        );
        let deadline = std::time::Instant::now() + Duration::from_secs(5);
        while !directory.path().join("child-ready").exists() && std::time::Instant::now() < deadline
        {
            assert!(
                child.0.try_wait().unwrap().is_none(),
                "lock probe exited before acquisition"
            );
            std::thread::sleep(Duration::from_millis(10));
        }
        assert!(directory.path().join("child-ready").exists());
        assert!(RecoveryLock::acquire(directory.path()).is_err());
        child.0.kill().unwrap();
        child.0.wait().unwrap();
        let recovered = RecoveryLock::acquire(directory.path()).unwrap();
        drop(recovered);
        assert_eq!(
            std::fs::read(directory.path().join(".recovery.lock")).unwrap(),
            b""
        );
    }
}

#[cfg(test)]
mod preparing_canonical_probe;

#[cfg(test)]
mod timed_fragment_tests {
    use super::*;

    fn boxed(kind: &[u8; 4], values: &[u32]) -> Vec<u8> {
        let mut bytes = (8 + values.len() as u32 * 4).to_be_bytes().to_vec();
        bytes.extend(kind);
        bytes.extend(values.iter().flat_map(|value| value.to_be_bytes()));
        bytes
    }

    fn container(kind: &[u8; 4], children: &[Vec<u8>]) -> Vec<u8> {
        let payload = children.concat();
        let mut bytes = (8 + payload.len() as u32).to_be_bytes().to_vec();
        bytes.extend(kind);
        bytes.extend(payload);
        bytes
    }

    fn fixture(directory: &Path) -> (PathBuf, Vec<u8>) {
        let track = container(
            b"trak",
            &[
                boxed(b"tkhd", &[0, 0, 0, 1]),
                container(b"mdia", &[boxed(b"mdhd", &[0, 0, 0, 30])]),
            ],
        );
        let defaults = container(b"mvex", &[boxed(b"trex", &[0, 1, 1, 1, 4, 0])]);
        std::fs::write(
            directory.join("init.mp4"),
            container(b"moov", &[track, defaults]),
        )
        .unwrap();
        let moof = container(
            b"moof",
            &[container(
                b"traf",
                &[
                    boxed(b"tfhd", &[0x20000, 1]),
                    boxed(b"tfdt", &[0, 0]),
                    boxed(b"trun", &[1, 60, 76]),
                ],
            )],
        );
        assert_eq!(moof.len(), 68);
        let mut complete = moof;
        complete.extend(boxed(b"mdat", &[42; 60]));
        let path = directory.join("segment_001.m4s.tmp");
        let mut partial = complete.clone();
        partial.extend(boxed(b"moof", &[0; 10]));
        partial.extend(&boxed(b"mdat", &[0; 60])[..24]);
        std::fs::write(&path, partial).unwrap();
        (path, complete)
    }

    #[test]
    fn discovers_pending_prefix_without_mutating_source() {
        let directory = tempfile::tempdir().unwrap();
        let (source, _) = fixture(directory.path());
        let before = recovery_snapshot(directory.path()).unwrap();
        let info = RecoveryManager::find_studio_fragments_with_init(directory.path());
        assert_eq!(info.fragments, [source]);
        assert_eq!(recovery_snapshot(directory.path()).unwrap(), before);
    }

    #[cfg(unix)]
    #[test]
    fn unreadable_pending_fragment_stays_listed_for_a_retry() {
        use std::os::unix::fs::PermissionsExt;

        let directory = tempfile::tempdir().unwrap();
        let (source, _) = fixture(directory.path());
        std::fs::set_permissions(&source, std::fs::Permissions::from_mode(0o000)).unwrap();
        if std::fs::File::open(&source).is_ok() {
            // Permissions do not apply (running as root).
            return;
        }
        let info = RecoveryManager::find_studio_fragments_with_init(directory.path());
        std::fs::set_permissions(&source, std::fs::Permissions::from_mode(0o644)).unwrap();
        assert_eq!(info.fragments, [source]);
    }

    #[test]
    fn studio_recovery_keeps_complete_prefix_and_original_bytes() {
        let directory = tempfile::tempdir().unwrap();
        let (source, complete) = fixture(directory.path());
        let original = std::fs::read(&source).unwrap();
        let marker = directory.path().join("segment_001.m4s.tmp.corrupt");
        std::fs::write(&marker, "truncated_fragment").unwrap();
        RecoveryManager::rescue_pending_tmp_fragments(directory.path(), None, true);
        let output = directory.path().join("segment_001.m4s");
        assert_eq!(std::fs::read(&output).unwrap(), complete);
        assert_eq!(std::fs::read(&source).unwrap(), original);
        RecoveryManager::rescue_pending_tmp_fragments(directory.path(), None, true);
        assert_eq!(std::fs::read(&output).unwrap(), complete);
        assert_eq!(
            RecoveryManager::find_studio_fragments_with_init(directory.path()).fragments,
            [output]
        );
    }

    #[test]
    fn instant_recovery_keeps_existing_partial_tail_policy() {
        let directory = tempfile::tempdir().unwrap();
        let (source, _) = fixture(directory.path());
        let original = std::fs::read(&source).unwrap();
        RecoveryManager::rescue_pending_tmp_fragments(directory.path(), None, false);
        assert!(!directory.path().join("segment_001.m4s").exists());
        assert_eq!(std::fs::read(source).unwrap(), original);
    }

    #[test]
    fn failed_prefix_copy_does_not_quarantine_valid_media() {
        let directory = tempfile::tempdir().unwrap();
        let (source, complete) = fixture(directory.path());
        let original = std::fs::read(&source).unwrap();
        RecoveryManager::rescue_pending_tmp_fragments_with_copy(
            directory.path(),
            None,
            true,
            |_, _, _| Err(std::io::Error::other("injected storage failure")),
        );
        assert!(
            !directory
                .path()
                .join("segment_001.m4s.tmp.corrupt")
                .exists()
        );
        assert!(!directory.path().join("segment_001.m4s").exists());
        assert_eq!(std::fs::read(&source).unwrap(), original);
        RecoveryManager::rescue_pending_tmp_fragments(directory.path(), None, true);
        assert_eq!(
            std::fs::read(directory.path().join("segment_001.m4s")).unwrap(),
            complete
        );
    }

    #[test]
    fn prefix_copy_never_overwrites_an_existing_destination() {
        let directory = tempfile::tempdir().unwrap();
        let (source, complete) = fixture(directory.path());
        let output = directory.path().join("segment_001.m4s");
        std::fs::write(&output, b"existing").unwrap();
        assert!(
            RecoveryManager::copy_recovered_prefix(&source, &output, complete.len() as u64)
                .is_err()
        );
        assert_eq!(std::fs::read(output).unwrap(), b"existing");
        assert_eq!(std::fs::read_dir(directory.path()).unwrap().count(), 3);
    }
}