Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

138 KB
Raw Blame
//! Caller-owned image execution host. One worker, two bounded queued inputs; browser pumping
//! uses the same incremental task without threads. Shared ownership never includes CAD state.

use std::collections::VecDeque;
#[cfg(not(target_arch = "wasm32"))]
use std::sync::Condvar;
use std::sync::{
    Arc, Mutex, Weak,
    atomic::{AtomicBool, AtomicU64, Ordering},
};

use serde::Serialize;
use sha2::{Digest, Sha256};

use super::{
    Admission, AlphaConvention, CancelToken, ColourEncoding, ErrorCode, FrameInfo, ImageExecutor, ImageRequest, ImageTask, ImageWork, Integrator,
    JobError, JobId, JobOptions, Phase, Progress, Result, TaskPoll,
};
use crate::{
    Availability, ExecutorDescriptor, ExecutorId, ProductScene, RenderFormat, RenderLimits, RenderMode, RenderOperation, RenderProfile, ScratchLayout,
};

#[cfg(test)]
use super::admit;

const MEMORY_LIMIT: u64 = 512 * 1024 * 1024;
const QUEUE_LIMIT: usize = 2;

#[cfg(test)]
struct CpuExecutor;
#[cfg(test)]
impl ImageExecutor for CpuExecutor {
    fn descriptor(&self) -> Result<ExecutorDescriptor> {
        Ok(ExecutorDescriptor {
            id: ExecutorId::new("cpu-product").map_err(|e| JobError::new(ErrorCode::Internal, e.to_string()))?,
            availability: Availability::Available,
            profiles: vec![RenderProfile {
                mode: RenderMode::Preview,
                operation: RenderOperation::Image,
                formats: vec![RenderFormat::Png],
                features: vec![crate::RenderFeature::Pbr],
            }],
            limits: RenderLimits::default(),
            scratch: ScratchLayout { sample_scale: 2, sample_bytes_per_pixel: 8, output_bytes_per_pixel: 8, encoding_bytes_per_pixel: 8 },
        })
    }

    fn admit(&self, scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
        if options != JobOptions::default() {
            return Err(JobError::new(ErrorCode::InvalidRequest, "CPU product does not support sampling or exposure controls"));
        }
        admit(scene, request)
    }
    fn begin(&self, scene: ProductScene, request: ImageRequest, _options: JobOptions, cancel: CancelToken) -> Result<Box<dyn ImageWork>> {
        Ok(Box::new(ImageTask::new(scene, request, cancel)?))
    }
}

// Completion notification precedes destruction of the worker's temporary handle.
// Lease tests join their owned, idle worker before checking exact retained bytes.
#[cfg(all(test, feature = "raytrace-cpu", not(target_arch = "wasm32")))]
impl ImageHost {
    pub(super) fn join_worker_for_test(&mut self) -> Result<()> {
        self.0.shared.stop.store(true, Ordering::Release);
        self.0.shared.wake.notify_all();
        let inner = Arc::get_mut(&mut self.0).ok_or_else(|| JobError::new(ErrorCode::Internal, "test must own its host"))?;
        if let Some(worker) = inner._worker.take() {
            worker.join().map_err(|_| JobError::new(ErrorCode::Internal, "test worker panicked"))?;
        }
        Ok(())
    }
}

#[cfg(test)]
#[path = "host_regrade_tests.rs"]
mod regrade_tests;
#[cfg(test)]
#[path = "host_tests.rs"]
mod tests;

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum HostKind {
    NativeWorker,
    Cooperative,
}

struct Budget {
    used: AtomicU64,
    limit: u64,
}
pub(crate) struct Reservation {
    budget: Arc<Budget>,
    bytes: u64,
}

impl Budget {
    fn reserve(self: &Arc<Self>, bytes: u64) -> Result<Reservation> {
        let mut used = self.used.load(Ordering::Acquire);
        loop {
            let next = used.checked_add(bytes).filter(|n| *n <= self.limit).ok_or_else(|| {
                JobError::new(ErrorCode::LimitExceeded, format!("image host admission pool is full ({} MiB)", self.limit / (1024 * 1024)))
            })?;
            match self.used.compare_exchange_weak(used, next, Ordering::AcqRel, Ordering::Acquire) {
                Ok(_) => break,
                Err(current) => used = current,
            }
        }
        Ok(Reservation { budget: self.clone(), bytes })
    }
}
impl Reservation {
    /// Transfer an already admitted portion without changing the pool's total.
    /// CPU progressive admission prepays at most two reusable checkpoint slots.
    fn split(&mut self, bytes: u64) -> Result<Self> {
        if bytes > self.bytes {
            return Err(JobError::new(ErrorCode::LimitExceeded, "preview exceeds its prepaid reservation"));
        }
        self.bytes -= bytes;
        Ok(Self { budget: self.budget.clone(), bytes })
    }

    /// Return a lease to the same prepaid pool without reserving memory again.
    fn merge_from(&mut self, other: &mut Self) -> Result<()> {
        if !Arc::ptr_eq(&self.budget, &other.budget) {
            return Err(JobError::new(ErrorCode::Internal, "checkpoint lease belongs to another pool"));
        }
        self.bytes = self.bytes.checked_add(other.bytes).ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "checkpoint lease overflow"))?;
        other.bytes = 0;
        Ok(())
    }

    pub(crate) fn shrink(&mut self, bytes: u64) -> Result<()> {
        if bytes > self.bytes {
            return Err(JobError::new(ErrorCode::LimitExceeded, "completed PNG exceeds its reservation"));
        }
        self.budget.used.fetch_sub(self.bytes - bytes, Ordering::AcqRel);
        self.bytes = bytes;
        Ok(())
    }
}
impl Drop for Reservation {
    fn drop(&mut self) {
        self.budget.used.fetch_sub(self.bytes, Ordering::AcqRel);
    }
}

/// Retained runtime input capacities survive work/PNG eviction through status handles.
fn retained_request_bytes(request: &ImageRequest) -> Result<u64> {
    request.raytrace.as_ref().map_or(Ok(0), |options| options.retained_bytes())
}

#[cfg(all(test, feature = "raytrace-cpu", not(target_arch = "wasm32")))]
mod light_union_lease_tests {
    use super::super::{DirectionalLightOptions, PunctualLightOptions, RaytraceOptions, led_strip::LedStripOptions};
    use super::*;
    fn request() -> Result<ImageRequest> {
        let mut options = RaytraceOptions {
            primary_samples: 16,
            lights: Some(vec![DirectionalLightOptions { direction: [0.0, 0.0, 1.0], color: [1.0; 3], intensity: 1.0 }; 8]),
            punctual_lights: Some(vec![
                PunctualLightOptions {
                    position_mm: [0.0, 0.0, 10.0],
                    color: [1.0; 3],
                    intensity: 1.0,
                    reference_distance_mm: 10.0,
                    minimum_distance_mm: 0.001,
                    cone: None
                };
                8
            ]),
            ..Default::default()
        };
        let strip = LedStripOptions {
            center_mm: [0.0, 0.0, 10.0],
            length_mm: 8.0,
            width_mm: 0.5,
            length_axis: [1.0, 0.0, 0.0],
            width_axis: [0.0, -1.0, 0.0],
            color: [1.0; 3],
            intensity: 2.0,
        };
        for _ in 0..4 {
            strip.append_to(&mut options, 64)?;
        }
        Ok(ImageRequest {
            studio_weights: None,
            environment: None,
            textures: None,
            integrator: Integrator::Raytrace,
            raytrace: Some(options),
            camera: Default::default(),
            width: 8,
            height: 8,
            background: [0; 3],
            transparent_background: false,
        })
    }
    fn scene() -> ProductScene {
        ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY }
    }
    #[test]
    fn normalized_union_uses_one_pool_and_keeps_record_lease_after_frame_eviction() {
        let mut host = CpuHost::for_platform().unwrap();
        let budget = host.0.shared.budget.clone();
        let request = request().unwrap();
        let bytes = retained_request_bytes(&request).unwrap() + request.retained_resource_metadata_bytes();
        let capacities = request
            .raytrace
            .as_ref()
            .map(|o| {
                (o.lights.as_ref().unwrap().capacity(), o.punctual_lights.as_ref().unwrap().capacity(), o.area_lights.as_ref().unwrap().capacity())
            })
            .unwrap();
        let job = host.submit(JobId { session: 1724, serial: 1, generation: 1 }, 1, scene(), request).unwrap();
        assert_eq!(job.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
        // Synchronize this test's completed worker before asserting final Arc release;
        // publication wakes waiters just before Running drops its temporary handle.
        host.0.shared.stop.store(true, Ordering::Release);
        host.0.shared.wake.notify_all();
        Arc::get_mut(&mut host.0).unwrap()._worker.take().unwrap().join().unwrap();
        let retained = job.0.request.raytrace.as_ref().unwrap();
        assert_eq!(
            capacities,
            (
                retained.lights.as_ref().unwrap().capacity(),
                retained.punctual_lights.as_ref().unwrap().capacity(),
                retained.area_lights.as_ref().unwrap().capacity()
            )
        );
        assert!(Arc::ptr_eq(&job.0._request_reservation.as_ref().unwrap().budget, &budget));
        assert_eq!(job.0._request_reservation.as_ref().unwrap().bytes, bytes);
        let frame = job.frame().unwrap().unwrap();
        job.0.data.lock().unwrap().frame = None;
        assert!(host.admitted_bytes() > bytes);
        drop(frame);
        assert_eq!(host.admitted_bytes(), bytes);
        let held = job.clone();
        drop(job);
        assert_eq!(host.admitted_bytes(), bytes);
        drop(held);
        assert_eq!(budget.used.load(Ordering::Acquire), 0);
    }
    #[test]
    fn failed_union_metadata_reservation_releases_work_and_does_not_enqueue() {
        let host = CpuHost::for_platform().unwrap();
        let request = request().unwrap();
        let work = admit(&scene(), &request).unwrap().estimated_total_bytes;
        let fill = host.0.shared.budget.reserve(host.pool_limit_bytes() - work).unwrap();
        let before = host.admitted_bytes();
        let result = host.submit(JobId { session: 1724, serial: 2, generation: 1 }, 1, scene(), request);
        assert_eq!(result.err().unwrap().code, ErrorCode::LimitExceeded);
        assert_eq!(host.admitted_bytes(), before);
        assert!(host.0.shared.queue.lock().unwrap().is_empty());
        drop(fill);
        assert_eq!(host.admitted_bytes(), 0);
    }
}

fn admit_request_sum(work_bytes: u64, request_bytes: u64) -> Result<()> {
    if work_bytes.checked_add(request_bytes).is_none_or(|sum| sum > super::image::MAX_JOB_BYTES) {
        return Err(JobError::new(ErrorCode::LimitExceeded, "render work and retained request exceed 384 MiB per-job admission"));
    }
    Ok(())
}

/// Borrow encoded bytes through the frame, so retaining the data also retains its admission lease.
#[derive(Clone, Copy, Debug, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum LinearColourEncoding {
    SceneLinearSrgbD65,
}
#[derive(Clone, Copy, Debug, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum LinearAlphaConvention {
    CoveragePremultiplied,
}
#[derive(Clone, Debug, Serialize)]
pub struct LinearMasterInfo {
    pub encoding: LinearColourEncoding,
    pub alpha: LinearAlphaConvention,
    pub bytes: u64,
    pub sha256: String,
}
struct RetainedPresentation {
    info: super::presentation::MasterPresentation,
    _reservation: Reservation,
}

pub struct RenderFrame {
    // Derivatives point directly at the original, never form a retention chain.
    source_master: Option<Arc<RenderFrame>>,
    presentation: Option<Arc<RetainedPresentation>>,
    pub info: FrameInfo,
    png: Vec<u8>,
    exr: Option<(Vec<u8>, LinearMasterInfo)>,
    _reservation: Reservation,
}
impl RenderFrame {
    pub fn master_source(self: &Arc<Self>) -> Result<Arc<Self>> {
        if let Some(source) = &self.source_master {
            return Ok(source.clone());
        }
        if self.exr.is_some() {
            return Ok(self.clone());
        }
        Err(JobError::new(ErrorCode::InvalidRequest, "completed image has no retained raw linear master"))
    }
    pub fn presentation(&self) -> Option<&super::presentation::MasterPresentation> {
        self.presentation.as_deref().map(|retained| &retained.info)
    }
    pub fn linear_exr(&self) -> Option<&[u8]> {
        self.exr.as_ref().map(|(bytes, _)| bytes.as_slice()).or_else(|| self.source_master.as_ref().and_then(|source| source.linear_exr()))
    }
    pub fn linear_master_info(&self) -> Option<&LinearMasterInfo> {
        self.exr.as_ref().map(|(_, info)| info).or_else(|| self.source_master.as_ref().and_then(|source| source.linear_master_info()))
    }
    pub fn png(&self) -> &[u8] {
        &self.png
    }
}

#[derive(Clone, Debug, Serialize)]
pub struct PreviewInfo {
    pub frame_sequence: u32,
    /// Uniform SPP when adaptive is absent; otherwise absolute completed iteration.
    pub samples_per_pixel: u32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub adaptive: Option<super::adaptive::AdaptivePreview>,
    pub frame: FrameInfo,
}

/// Immutable checkpoint bytes retain their own transferred host lease. Keeping
/// an older preview alive never makes its memory disappear from pool accounting.
pub struct RenderPreview {
    pub info: PreviewInfo,
    png: Vec<u8>,
    _reservation: CheckpointLease,
}

/// Two reusable, immutable complete-pass slots. No consumer acknowledgement or
/// queue: externally pinned slots are diagnosed and never stall final work.
struct CheckpointCredits {
    state: Mutex<CheckpointCreditState>,
    slot_bytes: u64,
    capacity: u64,
}
struct CheckpointCreditState {
    free: Reservation,
    closed: bool,
}
impl CheckpointCredits {
    fn new(reservation: &mut Reservation, slot_bytes: u64, slots: u32) -> Result<Arc<Self>> {
        if !(1..=2).contains(&slots) || slot_bytes == 0 {
            return Err(JobError::new(ErrorCode::InvalidRequest, "checkpoint credits require one or two finite slots"));
        }
        let capacity = slot_bytes
            .checked_mul(u64::from(slots))
            .and_then(|n| n.checked_add(FRAME_METADATA_BYTES))
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "checkpoint credit capacity overflow"))?;
        let free = reservation.split(capacity)?;
        Ok(Arc::new(Self { state: Mutex::new(CheckpointCreditState { free, closed: false }), slot_bytes, capacity }))
    }
    fn acquire(self: &Arc<Self>) -> Result<Option<CheckpointLease>> {
        let mut state = self.state.lock().map_err(|_| JobError::new(ErrorCode::Internal, "checkpoint credit lock poisoned"))?;
        if state.closed {
            return Err(JobError::new(ErrorCode::Cancelled, "checkpoint credits are closed"));
        }
        let needed = self
            .slot_bytes
            .checked_add(FRAME_METADATA_BYTES)
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "checkpoint credit bound overflow"))?;
        if state.free.bytes < needed {
            return Ok(None);
        }
        let reservation = state.free.split(self.slot_bytes)?;
        Ok(Some(CheckpointLease { reservation, credits: self.clone() }))
    }
    fn close(&self) {
        let mut state = match self.state.lock() {
            Ok(state) => state,
            Err(error) => error.into_inner(),
        };
        state.closed = true;
        let _ = state.free.shrink(0);
    }
}
struct CheckpointLease {
    reservation: Reservation,
    credits: Arc<CheckpointCredits>,
}
impl std::ops::Deref for CheckpointLease {
    type Target = Reservation;
    fn deref(&self) -> &Reservation {
        &self.reservation
    }
}
impl Drop for CheckpointLease {
    fn drop(&mut self) {
        let mut state = match self.credits.state.lock() {
            Ok(state) => state,
            Err(error) => {
                let mut state = error.into_inner();
                state.closed = true;
                let _ = state.free.shrink(0);
                state
            }
        };
        if !state.closed {
            if self.reservation.bytes <= self.credits.slot_bytes
                && state.free.bytes.checked_add(self.reservation.bytes).is_some_and(|n| n <= self.credits.capacity)
                && state.free.merge_from(&mut self.reservation).is_ok()
            {
                return;
            }
            state.closed = true;
            let _ = state.free.shrink(0);
        }
    }
}

impl RenderPreview {
    pub fn png(&self) -> &[u8] {
        &self.png
    }
}

/// Metadata for either runtime environment contract; wire objects retain their original shape.
#[derive(Clone, Debug, Serialize)]
#[serde(untagged)]
pub enum JobEnvironmentInfo {
    Cpu(crate::lighting::environment_input::EnvironmentInfo),
    Gpu(crate::lighting::environment::EnvironmentInfo),
}

#[derive(Clone, Debug, Serialize)]
pub struct JobStatus {
    /// Complete passes omitted only when both prepaid snapshots are externally retained.
    /// Final rendering continues; this is not a dropped sample or a stalled job.
    pub preview_retention_skips: u32,
    /// This request still renders final output, but has no intermediate-image route.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub preview_unavailable_reason: Option<&'static str>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub punctual_diagnostics: Option<super::PunctualDiagnostics>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub presentation: Option<super::presentation::MasterPresentation>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sampling: Option<super::adaptive::SamplingReport>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub linear_master: Option<LinearMasterInfo>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub preview: Option<PreviewInfo>,
    pub textures: Option<super::textures::TextureSummary>,
    pub options: JobOptions,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub environment: Option<JobEnvironmentInfo>,
    pub job: JobId,
    pub scene_generation: u64,
    pub request: ImageRequest,
    pub resolved: crate::ResolvedRequest,
    pub progress: Progress,
    pub error: Option<JobError>,
    pub frame: Option<FrameInfo>,
}

struct Data {
    preview_retention_skips: u32,
    completed_duration: Option<std::time::Duration>,
    punctual_diagnostics: Option<super::PunctualDiagnostics>,
    sampling: Option<super::adaptive::SamplingReport>,
    progress: Progress,
    error: Option<JobError>,
    frame: Option<Arc<RenderFrame>>,
    preview: Option<Arc<RenderPreview>>,
}
struct Record {
    work_released: AtomicBool,
    preview_unavailable_reason: Option<&'static str>,
    started: web_time::Instant,
    presentation: Option<Arc<RetainedPresentation>>,
    textures: Option<super::textures::TextureSummary>,
    options: Option<RetainedOptions>,
    environment: Option<JobEnvironmentInfo>,
    _request_reservation: Option<Reservation>,
    id: JobId,
    scene_generation: u64,
    request: ImageRequest,
    resolved: crate::ResolvedRequest,
    cancel: CancelToken,
    data: Mutex<Data>,
    #[cfg(not(target_arch = "wasm32"))]
    done: Condvar,
}

impl Record {
    fn options(&self) -> Result<JobOptions> {
        match &self.options {
            None => Ok(JobOptions::default()),
            Some(slot) => slot.0.first().copied().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing retained render options")),
        }
    }
    fn notify(&self) {
        #[cfg(not(target_arch = "wasm32"))]
        self.done.notify_all();
    }
}

#[derive(Clone)]
pub struct JobHandle(Arc<Record>);

impl JobHandle {
    pub fn id(&self) -> JobId {
        self.0.id
    }
    /// Time since submission, including queueing and preparation.
    pub fn elapsed(&self) -> std::time::Duration {
        self.0.started.elapsed()
    }
    /// True only after queued/running captures, tasks and their work reservations
    /// have been dropped. A terminal phase alone does not prove resource release.
    /// Retained final/preview images and status-input leases remain owned by their
    /// observers; callers retiring a job must drop those handles after this barrier.
    pub fn work_released(&self) -> bool {
        self.0.work_released.load(Ordering::Acquire)
    }
    /// Submission-to-publication time, captured once by the host, independent of UI polling.
    pub fn completed_duration(&self) -> Result<Option<std::time::Duration>> {
        self.0.data.lock().map(|data| data.completed_duration).map_err(|_| JobError::new(ErrorCode::Internal, "render duration lock poisoned"))
    }
    pub fn status(&self) -> Result<JobStatus> {
        let data = self.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render status lock poisoned"))?;
        Ok(JobStatus {
            preview_retention_skips: data.preview_retention_skips,
            preview_unavailable_reason: self.0.preview_unavailable_reason,
            punctual_diagnostics: data.punctual_diagnostics,
            presentation: self.0.presentation.as_deref().map(|retained| retained.info.clone()),
            sampling: data.sampling.clone(),
            linear_master: data.frame.as_ref().and_then(|frame| frame.linear_master_info().cloned()),
            preview: data.preview.as_ref().map(|preview| preview.info.clone()),
            textures: self.0.textures.clone(),
            options: self.0.options()?,
            environment: self.0.environment.clone(),
            job: self.0.id,
            scene_generation: self.0.scene_generation,
            request: self.0.request.clone(),
            resolved: self.0.resolved.clone(),
            progress: data.progress,
            error: data.error.clone(),
            frame: data.frame.as_ref().map(|f| f.info.clone()),
        })
    }
    pub fn cancel(&self) -> Result<JobStatus> {
        {
            let mut data = self.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render status lock poisoned"))?;
            if !data.progress.phase.terminal() {
                self.0.cancel.cancel();
                data.preview = None;
                data.progress.phase = if data.progress.phase == Phase::Queued { Phase::Cancelled } else { Phase::Cancelling };
            }
        }
        self.0.notify();
        self.status()
    }

    /// Native application helper; engine status commands remain non-blocking.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn wait_timeout(&self, timeout: std::time::Duration) -> Result<JobStatus> {
        let data = self.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render status lock poisoned"))?;
        let (data, timed) = self
            .0
            .done
            .wait_timeout_while(data, timeout, |d| !d.progress.phase.terminal())
            .map_err(|_| JobError::new(ErrorCode::Internal, "render completion lock poisoned"))?;
        if timed.timed_out() && !data.progress.phase.terminal() {
            return Err(JobError::new(ErrorCode::TimedOut, "render wait timed out"));
        }
        drop(data);
        self.status()
    }
    pub fn frame(&self) -> Result<Option<Arc<RenderFrame>>> {
        let data = self.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render result lock poisoned"))?;
        let frame = data.frame.clone();
        if frame.as_ref().is_some_and(|f| f.info.job != self.0.id || f.info.scene_generation != self.0.scene_generation) {
            return Err(JobError::new(ErrorCode::WrongOwner, "render frame identity does not match its job"));
        }
        Ok(frame)
    }

    /// A provisional complete-pass image, never the final/export frame slot.
    pub fn preview(&self) -> Result<Option<Arc<RenderPreview>>> {
        let data = self.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render preview lock poisoned"))?;
        let preview = data.preview.clone();
        if preview.as_ref().is_some_and(|p| p.info.frame.job != self.0.id || p.info.frame.scene_generation != self.0.scene_generation) {
            return Err(JobError::new(ErrorCode::WrongOwner, "render preview identity does not match its job"));
        }
        Ok(preview)
    }
}

/// The last field of Work and Running. Rust drops earlier fields first, so
/// observers cannot see this barrier until captured inputs, executor tasks,
/// pending PNGs, reservations and checkpoint credits have actually been released.
struct WorkRelease(Weak<Record>);
impl Drop for WorkRelease {
    fn drop(&mut self) {
        if let Some(record) = self.0.upgrade() {
            record.work_released.store(true, Ordering::Release);
            record.notify();
        }
    }
}

/// Independently prepaid captured metadata, retained beyond any one Work/frame.
/// The owner must place its backing before this field so backing drops first.
pub struct RetainedMetadata(Reservation);
impl RetainedMetadata {
    pub fn bytes(&self) -> u64 {
        self.0.bytes
    }
}

/// The explicit execution envelope for NEW common map capture. Registered
/// executors use their actual host limit and never a synthetic CPU profile.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CaptureProfile {
    CpuRaytrace(super::CpuBudget),
    Registered,
}
impl CaptureProfile {
    fn integrator(self) -> Integrator {
        match self {
            Self::CpuRaytrace(_) => Integrator::Raytrace,
            Self::Registered => Integrator::Raster,
        }
    }
    fn budget(self) -> super::CpuBudget {
        match self {
            Self::CpuRaytrace(budget) => budget,
            Self::Registered => super::CpuBudget::Compact,
        }
    }
}

// Serialize metadata directly into the existing hash state: no captured source,
// descriptor JSON Value or retained descriptor Vec/String clone is created.
fn capture_fingerprint(value: &impl Serialize) -> Result<[u8; 32]> {
    struct HashWriter(Sha256);
    impl std::io::Write for HashWriter {
        fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
            self.0.update(bytes);
            Ok(bytes.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }
    let mut writer = HashWriter(Sha256::new());
    serde_json::to_writer(&mut writer, value).map_err(|e| JobError::new(ErrorCode::Internal, format!("capture descriptor: {e}")))?;
    Ok(writer.0.finalize().into())
}

/// Move-only same-pool high-water credit acquired BEFORE common captured map
/// backing. Its enclosing caller must drop that backing before this lease.
/// Submission consumes it into the ordinary PreparedSubmission reservations.
/// Any high-water excess over the final layout remains billed as preparation
/// backing until Work releases; Record retains only its normal summary lease.
pub struct CaptureLease<'a> {
    host: ImageHost,
    profile: CaptureProfile,
    descriptor: [u8; 32],
    execution: [u8; 32],
    retained: Option<&'a RetainedMetadata>,
    cancel: CancelToken,
    reservation: Reservation,
    consumed: bool,
}
impl CaptureLease<'_> {
    pub fn bytes(&self) -> u64 {
        self.reservation.bytes
    }
    fn check(&self, cancel: &CancelToken) -> Result<()> {
        if self.consumed {
            return Err(JobError::new(ErrorCode::InvalidRequest, "capture credit was already consumed"));
        }
        if !Arc::ptr_eq(&self.cancel.0, &cancel.0) {
            return Err(JobError::new(ErrorCode::WrongOwner, "capture cancellation owner changed"));
        }
        self.cancel.check()?;
        cancel.check()?;
        let descriptor = self.host.capture_descriptor(self.profile)?;
        if capture_fingerprint(&descriptor)? != self.descriptor {
            return Err(JobError::new(ErrorCode::HostUnavailable, "capture executor metadata changed"));
        }
        Ok(())
    }
    /// Add only the difference between the next live peak and existing credit.
    /// Retired duplicate/pending buffers reuse this high-water lease; no release
    /// or reacquisition is needed between capture phases.
    pub fn try_extend(&mut self, bytes: u64, cancel: &CancelToken) -> Result<()> {
        self.check(cancel)?;
        let total = self.bytes().checked_add(bytes).ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "capture credit overflow"))?;
        self.host.check_request_sum(total, self.retained.map_or(0, RetainedMetadata::bytes), self.profile.budget())?;
        let mut extra = self.host.0.shared.budget.reserve(bytes)?;
        self.reservation.merge_from(&mut extra)
    }
    fn check_request(&self, host: &ImageHost, request: &ImageRequest, cancel: &CancelToken, retained: Option<&RetainedMetadata>) -> Result<()> {
        if !self.host.same_host(host) {
            return Err(JobError::new(ErrorCode::WrongOwner, "capture credit belongs to a different installed host"));
        }
        self.check(cancel)?;
        let selected = if host.0.executor.is_some() { CaptureProfile::Registered } else { CaptureProfile::CpuRaytrace(request.cpu_budget()) };
        if self.profile != selected || request.integrator != self.profile.integrator() {
            return Err(JobError::new(ErrorCode::WrongOwner, "capture execution profile changed"));
        }
        host.capture_retained_context(retained)?;
        let same_retained = match (self.retained, retained) {
            (None, None) => true,
            (Some(before), Some(after)) => std::ptr::eq(before, after),
            _ => false,
        };
        if !same_retained {
            return Err(JobError::new(ErrorCode::WrongOwner, "capture retained-metadata context changed"));
        }
        let bytes = request
            .textures
            .as_ref()
            .ok_or_else(|| JobError::new(ErrorCode::InvalidRequest, "capture credit requires common texture backing"))?
            .captured_bytes()?;
        if bytes > self.bytes() {
            return Err(JobError::new(ErrorCode::LimitExceeded, "captured texture backing exceeds its prepaid credit"));
        }
        Ok(())
    }
}

/// Captured, completely validated input under the existing host budget. This
/// has no job identity, document or camera mutation, and cannot be cloned.
pub struct PreparedSubmission {
    scene: ProductScene,
    public_request: ImageRequest,
    work_request: Option<ImageRequest>,
    options: Option<RetainedOptions>,
    environment: Option<crate::lighting::environment_input::EnvironmentInput>,
    environment_info: Option<JobEnvironmentInfo>,
    textures: Option<super::textures::TextureSummary>,
    resolved: crate::ResolvedRequest,
    admission: Admission,
    cancel: CancelToken,
    #[cfg(feature = "raytrace-cpu")]
    proof: Vec<crate::raytrace::image::CertifiedOptics>,
    request_reservation: Option<Reservation>,
    reservation: Reservation,
    host: ImageHost,
}
impl PreparedSubmission {
    /// Check a simultaneously retained metadata owner under the same unchanged
    /// per-job/profile cap. It is not funded by a Work/frame lease.
    pub fn check_retained_metadata(&self, bytes: u64) -> Result<()> {
        let retained = self
            .request_reservation
            .as_ref()
            .map_or(0, |r| r.bytes)
            .checked_add(bytes)
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "retained metadata byte overflow"))?;
        self.host.check_request_sum(self.reservation.bytes, retained, self.request().cpu_budget())
    }
    pub fn reserve_retained_metadata(&self, bytes: u64) -> Result<RetainedMetadata> {
        self.check_retained_metadata(bytes)?;
        self.host.0.shared.budget.reserve(bytes).map(RetainedMetadata)
    }
    pub fn request(&self) -> &ImageRequest {
        self.work_request.as_ref().unwrap_or(&self.public_request)
    }
    pub fn admission(&self) -> Admission {
        self.admission
    }
    pub fn check_cancel(&self) -> Result<()> {
        self.cancel.check()
    }
    pub fn executor(&self) -> &crate::ExecutorId {
        &self.resolved.executor
    }
    pub fn host(&self) -> &ImageHost {
        &self.host
    }
    pub fn options(&self) -> Result<JobOptions> {
        match &self.options {
            None => Ok(JobOptions::default()),
            Some(slot) => slot.0.first().copied().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing prepared render options")),
        }
    }
}

struct Work {
    #[cfg(feature = "raytrace-cpu")]
    proof: Vec<crate::raytrace::image::CertifiedOptics>,
    regrade: Option<(Arc<RenderFrame>, super::presentation::Presentation)>,
    request: Option<ImageRequest>,
    executor: Option<Arc<dyn ImageExecutor>>,
    environment: Option<crate::lighting::environment_input::EnvironmentInput>,
    scene: ProductScene,
    handle: JobHandle,
    encoded_limit: u64,
    reservation: Reservation,
    // Must remain last: see WorkRelease.
    _work_release: WorkRelease,
}
// A queued request moves into the task at begin; no task allocation exists yet.
// Its fixed queue metadata must fit the same already prepaid task allowance,
// independently of the separate retained-Record header reservation.
const _: [(); 1] = [(); (std::mem::size_of::<Work>() <= 4096) as usize];
// One host advance hashes at most four 16 KiB chunks, independently of the
// integrator's quantum. The unchanged work reservation covers the sole PNG and
// this fixed state until publication; it is not another image task or pool.
const PNG_HASH_CHUNK_BYTES: usize = 16_384;
const PNG_HASH_CHUNKS_PER_ADVANCE: usize = 4;
pub(crate) const FRAME_METADATA_BYTES: u64 = 1024;
#[cfg(feature = "raytrace-cpu")]
const PREPARED_PROOF_HEADER_BYTES: usize = std::mem::size_of::<Vec<crate::raytrace::image::CertifiedOptics>>();
#[cfg(not(feature = "raytrace-cpu"))]
const PREPARED_PROOF_HEADER_BYTES: usize = 0;
// Preparation/enqueue only moves fixed headers. All source/resource capacities
// and optical proof backing have independent admission; none survives without
// the owning work/request lease. Keep the existing preparation allowance.
const _: [(); 1] =
    [(); (std::mem::size_of::<PreparedSubmission>() + std::mem::size_of::<Work>() + std::mem::size_of::<Record>() + std::mem::size_of::<Running>()
        <= super::image::PREPARATION_METADATA_BYTES as usize) as usize];

struct PendingPng {
    png: Vec<u8>,
    digest: Sha256,
    png_digest: Option<sha2::digest::Output<Sha256>>,
    hashed: usize,
    preview_samples: Option<u32>,
    exr: Option<Vec<u8>>,
    exr_hashed: usize,
}
// Keep the new fixed completion state within the existing metadata allowance
// even if the hashing dependency's representation changes on another target.
const _: [(); 1] = [(); (std::mem::size_of::<PendingPng>() <= 512) as usize];
const _: [(); 1] = [(); (std::mem::size_of::<Running>()
    + std::mem::size_of::<RenderFrame>()
    + std::mem::size_of::<RenderPreview>()
    + PREPARED_PROOF_HEADER_BYTES
    + 64
    + 2 * crate::MAX_RENDER_ID_BYTES
    + 32
    <= FRAME_METADATA_BYTES as usize) as usize];

impl PendingPng {
    fn new(png: Vec<u8>) -> Self {
        Self { png, digest: Sha256::new(), png_digest: None, hashed: 0, preview_samples: None, exr: None, exr_hashed: 0 }
    }

    fn preview(png: Vec<u8>, samples: u32) -> Self {
        Self { preview_samples: Some(samples), ..Self::new(png) }
    }

    fn step(&mut self, units: usize, cancel: &CancelToken) -> Result<bool> {
        cancel.check()?;
        for _ in 0..units.min(PNG_HASH_CHUNKS_PER_ADVANCE) {
            self.finish_png_digest();
            let (bytes, hashed) = if self.hashed < self.png.len() {
                (&self.png, &mut self.hashed)
            } else if let Some(exr) = self.exr.as_ref().filter(|exr| self.exr_hashed < exr.len()) {
                (exr, &mut self.exr_hashed)
            } else {
                break;
            };
            let end = hashed.saturating_add(PNG_HASH_CHUNK_BYTES).min(bytes.len());
            self.digest.update(bytes.get(*hashed..end).ok_or_else(|| JobError::new(ErrorCode::Internal, "missing completed image digest chunk"))?);
            *hashed = end;
            cancel.check()?;
        }
        self.finish_png_digest();
        Ok(self.hashed == self.png.len() && self.exr.as_ref().is_none_or(|exr| self.exr_hashed == exr.len()))
    }
    fn finish_png_digest(&mut self) {
        if self.hashed == self.png.len() && self.png_digest.is_none() {
            // PNG and EXR are scanned sequentially. Keep only its fixed digest
            // while resetting the same SHA state for the optional raw companion.
            self.png_digest = Some(self.digest.finalize_reset());
        }
    }
    fn progress(&self) -> Progress {
        Progress {
            phase: Phase::Encoding,
            done: self.hashed as u64 + self.exr_hashed as u64,
            total: self.png.len() as u64 + self.exr.as_ref().map_or(0, |bytes| bytes.len() as u64),
        }
    }
}

struct Running {
    source_master: Option<Arc<RenderFrame>>,
    task: Option<WorkTask>,
    pending_png: Option<PendingPng>,
    handle: JobHandle,
    reservation: Option<Reservation>,
    next_preview_sequence: u32,
    next_checkpoint_pass: u32,
    checkpoint_target: u32,
    checkpoints: Option<Arc<CheckpointCredits>>,
    // Must remain last: see WorkRelease.
    _work_release: WorkRelease,
}

impl Drop for Running {
    fn drop(&mut self) {
        if let Some(credits) = &self.checkpoints {
            credits.close();
        }
    }
}

/// One independently prepaid options value. Exact defaults have no slot; authored
/// option/effect presence is structural and is never normalized into that case.
/// The containing Record is smaller than its previous inline JobOptions field.
/// This lease survives work release and frame eviction through retained handles.
struct RetainedOptions(Vec<JobOptions>);
impl RetainedOptions {
    fn new(options: JobOptions) -> Result<Self> {
        let _ = options.retained_bytes()?;
        let mut values = Vec::new();
        values.try_reserve_exact(1).map_err(|_| JobError::new(ErrorCode::AllocationFailed, "could not reserve retained render options"))?;
        if values.capacity() != 1 {
            return Err(JobError::new(ErrorCode::LimitExceeded, "retained render options exceed their prepaid capacity"));
        }
        values.push(options);
        Ok(Self(values))
    }
}
const _: [(); 1] = [(); (std::mem::size_of::<Option<RetainedOptions>>() <= std::mem::size_of::<JobOptions>()) as usize];

/// One fallibly allocated task, keeping the dispatch enum small in either build.
/// Its bounded metadata allocation fits the existing per-job task allowance.
struct TaskSlot<T>(Vec<T>);
impl<T> TaskSlot<T> {
    fn new(task: T) -> Result<Self> {
        if std::mem::size_of::<T>() > 4096 {
            return Err(JobError::new(ErrorCode::LimitExceeded, "render task metadata exceeds its admission allowance"));
        }
        let mut tasks = Vec::new();
        tasks.try_reserve_exact(1).map_err(|_| JobError::new(ErrorCode::AllocationFailed, "could not reserve render task slot"))?;
        if tasks.capacity() != 1 {
            return Err(JobError::new(ErrorCode::LimitExceeded, "render task slot exceeds its bounded capacity"));
        }
        tasks.push(task);
        Ok(Self(tasks))
    }
    fn get_mut(&mut self) -> Result<&mut T> {
        self.0.first_mut().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing render task slot"))
    }
}
enum WorkTask {
    Regrade(TaskSlot<super::regrade::RegradeTask>),
    Registered(Box<dyn ImageWork>),
    Raster(TaskSlot<ImageTask>),
    #[cfg(feature = "raytrace-cpu")]
    Raytrace(TaskSlot<crate::raytrace::image::ImageTask>),
}

enum WorkPoll {
    Existing(TaskPoll),
    Preview { png: Vec<u8>, samples_per_pixel: u32 },
}

impl WorkTask {
    fn punctual_diagnostics(&self) -> Option<super::PunctualDiagnostics> {
        match self {
            #[cfg(feature = "raytrace-cpu")]
            Self::Raytrace(slot) => slot.0.first().and_then(|task| task.punctual_diagnostics()),
            Self::Registered(task) => task.punctual_diagnostics(),
            _ => None,
        }
    }

    fn source_master(&self) -> Result<Option<Arc<RenderFrame>>> {
        match self {
            Self::Regrade(slot) => {
                slot.0.first().map(|task| Some(task.source())).ok_or_else(|| JobError::new(ErrorCode::Internal, "missing master task slot"))
            }
            _ => Ok(None),
        }
    }
    fn sampling_report(&self) -> Option<super::adaptive::SamplingReport> {
        match self {
            Self::Registered(task) => task.sampling_report(),
            #[cfg(feature = "raytrace-cpu")]
            Self::Raytrace(slot) => slot.0.first().and_then(|task| task.sampling_report()),
            _ => None,
        }
    }
    fn take_linear_exr(&mut self) -> Option<Vec<u8>> {
        match self {
            Self::Registered(task) => task.take_linear_exr(),
            #[cfg(feature = "raytrace-cpu")]
            Self::Raytrace(task) => task.0.first_mut().and_then(|task| task.take_linear_exr()),
            _ => None,
        }
    }
    fn new(
        scene: ProductScene,
        request: ImageRequest,
        cancel: CancelToken,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
        #[cfg(feature = "raytrace-cpu")] proof: Option<crate::raytrace::image::CertifiedOptics>,
    ) -> Result<Self> {
        let _ = &environment;
        match request.integrator {
            Integrator::Raster => ImageTask::new(scene, request, cancel).and_then(TaskSlot::new).map(Self::Raster),
            Integrator::Raytrace => {
                #[cfg(feature = "raytrace-cpu")]
                {
                    let options = request.raytrace.clone().unwrap_or_default();
                    crate::raytrace::image::ImageTask::new_prepared(scene, request, cancel, options, environment, proof)
                        .and_then(TaskSlot::new)
                        .map(Self::Raytrace)
                }
                #[cfg(not(feature = "raytrace-cpu"))]
                {
                    Err(JobError::new(ErrorCode::HostUnavailable, "CPU raytracing is not compiled in; enable raytrace-cpu"))
                }
            }
        }
    }

    fn step(&mut self, units: usize) -> Result<WorkPoll> {
        match self {
            Self::Regrade(task) => task.get_mut()?.step(units).map(WorkPoll::Existing),
            Self::Registered(task) => {
                let poll = task.step(units)?;
                if let Some(preview) = task.take_preview() {
                    if !matches!(poll, TaskPoll::Pending(_)) {
                        return Err(JobError::new(ErrorCode::Internal, "executor published provisional and final output together"));
                    }
                    Ok(WorkPoll::Preview { png: preview.png, samples_per_pixel: preview.samples_per_pixel })
                } else {
                    Ok(WorkPoll::Existing(poll))
                }
            }
            Self::Raster(task) => task.get_mut()?.step(units).map(WorkPoll::Existing),
            #[cfg(feature = "raytrace-cpu")]
            Self::Raytrace(task) => Ok(match task.get_mut()?.step_with_previews(units)? {
                crate::raytrace::image::ImagePoll::Pending(progress) => WorkPoll::Existing(TaskPoll::Pending(progress)),
                crate::raytrace::image::ImagePoll::Complete(png) => WorkPoll::Existing(TaskPoll::Complete(png)),
                crate::raytrace::image::ImagePoll::Preview { png, samples_per_pixel } => WorkPoll::Preview { png, samples_per_pixel },
            }),
        }
    }
}

fn terminal(handle: &JobHandle, error: JobError) {
    if let Ok(mut data) = handle.0.data.lock() {
        if data.progress.phase == Phase::Completed {
            return;
        }
        if handle.0.cancel.is_cancelled() || error.code == ErrorCode::Cancelled {
            data.progress.phase = Phase::Cancelled;
            data.error = None;
        } else {
            data.progress.phase = Phase::Failed;
            data.error = Some(error);
        }
        data.frame = None;
        data.preview = None;
    }
    handle.0.notify();
}

impl Running {
    fn begin(mut work: Work) -> Option<Self> {
        let options = match work.handle.0.options() {
            Ok(options) => options,
            Err(error) => {
                terminal(&work.handle, error);
                return None;
            }
        };
        let checkpoint_target = if work.regrade.is_some() {
            0
        } else if let Some(executor) = &work.executor {
            executor.preview_samples(options).unwrap_or(0)
        } else if work.handle.0.request.integrator == Integrator::Raytrace {
            work.handle.0.request.raytrace.as_ref().map_or(Ok(0), super::RaytraceOptions::preview_target).unwrap_or(0)
        } else {
            0
        };
        let checkpoints = (|| {
            let slots = checkpoint_target.saturating_sub(1).min(2);
            if slots == 0 {
                return Ok(None);
            }
            let slot_bytes = work
                .encoded_limit
                .checked_add(FRAME_METADATA_BYTES)
                .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "checkpoint slot overflow"))?;
            CheckpointCredits::new(&mut work.reservation, slot_bytes, slots).map(Some)
        })();
        let checkpoints = match checkpoints {
            Ok(credits) => credits,
            Err(error) => {
                terminal(&work.handle, error);
                return None;
            }
        };
        if work.handle.0.cancel.is_cancelled() {
            terminal(&work.handle, JobError::new(ErrorCode::Cancelled, "render cancelled"));
            return None;
        }
        if let Ok(mut data) = work.handle.0.data.lock()
            && !work.handle.0.cancel.is_cancelled()
        {
            data.progress.phase = Phase::Preparing;
        }
        let task = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            if let Some((source, presentation)) = work.regrade {
                super::regrade::RegradeTask::new(source, presentation, work.handle.0.cancel.clone()).and_then(TaskSlot::new).map(WorkTask::Regrade)
            } else if let Some(executor) = work.executor {
                let request = work.request.ok_or_else(|| JobError::new(ErrorCode::Internal, "missing registered executor request"))?;
                executor.begin(work.scene, request, options, work.handle.0.cancel.clone()).map(WorkTask::Registered)
            } else {
                // CPU textures are work-owned just like registered resources. The
                // public/status request has already had those Arcs removed.
                let request = work.request.unwrap_or_else(|| work.handle.0.request.clone());
                WorkTask::new(
                    work.scene,
                    request,
                    work.handle.0.cancel.clone(),
                    work.environment,
                    #[cfg(feature = "raytrace-cpu")]
                    work.proof.pop(),
                )
            }
        }))
        .unwrap_or_else(|_| Err(JobError::new(ErrorCode::Internal, "image executor failed while preparing the job")));
        match task {
            Ok(task) => Some(Self {
                source_master: None,
                task: Some(task),
                pending_png: None,
                handle: work.handle,
                reservation: Some(work.reservation),
                next_preview_sequence: 1,
                next_checkpoint_pass: 1,
                checkpoint_target,
                checkpoints,
                _work_release: work._work_release,
            }),
            Err(e) => {
                terminal(&work.handle, e);
                None
            }
        }
    }

    fn advance(&mut self, units: usize) -> Result<bool> {
        self.handle.0.cancel.check()?;
        if self.pending_png.is_some() {
            return self.advance_png(units);
        }
        let result = self.task.as_mut().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing render task"))?.step(units)?;
        let mut data = self.handle.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render status lock poisoned"))?;
        data.punctual_diagnostics = self.task.as_ref().and_then(WorkTask::punctual_diagnostics);
        // The final publication check is under the same lock as cancellation.
        if self.handle.0.cancel.is_cancelled() {
            data.progress.phase = Phase::Cancelled;
            data.frame = None;
            data.preview = None;
            self.handle.0.notify();
            return Ok(false);
        }
        match result {
            WorkPoll::Existing(TaskPoll::Pending(progress)) => {
                data.progress = progress;
                Ok(true)
            }
            WorkPoll::Existing(TaskPoll::Complete(png)) => {
                // Drop every integrator-owned capture/scratch buffer first, but
                // keep the original admission lease while hashing the sole PNG.
                self.source_master = self.task.as_ref().map(WorkTask::source_master).transpose()?.flatten();
                data.sampling = self.task.as_ref().and_then(WorkTask::sampling_report);
                let exr = self.task.as_mut().and_then(WorkTask::take_linear_exr);
                let retain_exr = self
                    .handle
                    .0
                    .request
                    .raytrace
                    .as_ref()
                    .and_then(|options| options.output.as_deref())
                    .map_or(self.handle.0.options()?.linear_exr, |output| output.linear_exr);
                if exr.is_some() != retain_exr {
                    return Err(JobError::new(ErrorCode::Internal, "linear master availability differs from the admitted request"));
                }
                if let Some(bytes) = &exr {
                    let limit = super::linear_exr::encoded_limit(self.handle.0.request.width, self.handle.0.request.height)?;
                    if bytes.len() < 8 || bytes.capacity() as u64 > limit || bytes.get(..8) != Some(&[0x76, 0x2f, 0x31, 0x01, 2, 0, 0, 0]) {
                        return Err(JobError::new(ErrorCode::LimitExceeded, "linear master exceeds its bound or has an invalid signature"));
                    }
                }
                self.task = None;
                let mut pending = PendingPng::new(png);
                pending.exr = exr;
                data.progress = pending.progress();
                self.pending_png = Some(pending);
                Ok(true)
            }
            WorkPoll::Preview { png, samples_per_pixel } => {
                // Retain the integrator/film and the entire remaining work lease.
                // Hash the checkpoint before making immutable bytes observable.
                let pending = PendingPng::preview(png, samples_per_pixel);
                data.progress = pending.progress();
                self.pending_png = Some(pending);
                Ok(true)
            }
        }
    }

    fn advance_png(&mut self, units: usize) -> Result<bool> {
        // No status/data lock is held while scanning the encoded image.
        let pending = self.pending_png.as_mut().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing pending PNG"))?;
        if !pending.step(units, &self.handle.0.cancel)? {
            let progress = pending.progress();
            let mut data = self.handle.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render status lock poisoned"))?;
            self.handle.0.cancel.check()?;
            data.progress = progress;
            return Ok(true);
        }
        let PendingPng { png, digest, png_digest, preview_samples, exr, .. } =
            self.pending_png.take().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing completed PNG digest"))?;
        let info = FrameInfo {
            job: self.handle.0.id,
            scene_generation: self.handle.0.scene_generation,
            backend: self.handle.0.resolved.backend.clone(),
            executor: self.handle.0.resolved.executor.clone(),
            width: self.handle.0.request.width,
            height: self.handle.0.request.height,
            encoding: ColourEncoding::Srgb,
            alpha: AlphaConvention::Straight,
            png_bytes: png.len() as u64,
            png_sha256: format!("{:x}", png_digest.ok_or_else(|| JobError::new(ErrorCode::Internal, "missing completed PNG digest"))?),
        };
        // Include the working digest/Vec metadata, completed frame layout,
        // actual hex allocation, bounded copied IDs and Arc/header allowance.
        // The PNG allocation itself is retained once and billed by capacity below.
        let frame_layout = if preview_samples.is_some() { std::mem::size_of::<RenderPreview>() } else { std::mem::size_of::<RenderFrame>() };
        // A retained checkpoint keeps its shared credit ledger alive even after
        // the running job closes it. Bill that fixed Arc payload/header through
        // the checkpoint's own metadata allowance as well as its PNG capacity.
        let checkpoint_metadata = if preview_samples.is_some() { std::mem::size_of::<CheckpointCredits>() + 32 } else { 0 };
        let fixed_metadata = std::mem::size_of::<Running>() + frame_layout + checkpoint_metadata + 2 * crate::MAX_RENDER_ID_BYTES + 32;
        let linear_digest_bytes = if exr.is_some() { 64 } else { 0 };
        if fixed_metadata
            .checked_add(info.png_sha256.capacity())
            .and_then(|n| n.checked_add(linear_digest_bytes))
            .is_none_or(|bytes| bytes > FRAME_METADATA_BYTES as usize)
        {
            return Err(JobError::new(ErrorCode::LimitExceeded, "PNG digest metadata exceeds its existing admission allowance"));
        }
        let mut data = self.handle.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render status lock poisoned"))?;
        // Cancellation shares this lock; a late cancel must win before frame
        // installation. The digest is complete; checkpoints retain task scratch,
        // while the final-only path has already released it.
        self.handle.0.cancel.check()?;
        if let Some(samples_per_pixel) = preview_samples {
            let target_samples = self.checkpoint_target;
            let frame_sequence = self.next_preview_sequence;
            let expected = Some(self.next_checkpoint_pass);
            if expected != Some(samples_per_pixel) || samples_per_pixel >= target_samples || self.task.is_none() {
                return Err(JobError::new(ErrorCode::Internal, "invalid progressive checkpoint sequence"));
            }
            let next_sequence = frame_sequence.checked_add(1).ok_or_else(|| JobError::new(ErrorCode::Internal, "preview sequence exhausted"))?;
            let credits = self.checkpoints.as_ref().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing checkpoint credits"))?;
            if (png.capacity() as u64).checked_add(FRAME_METADATA_BYTES).is_none_or(|bytes| bytes > credits.slot_bytes) {
                return Err(JobError::new(ErrorCode::LimitExceeded, "checkpoint PNG exceeds its admitted slot"));
            }
            let mut reservation = credits.acquire()?;
            if reservation.is_none() {
                // Reclaim a host-only snapshot without removing a consumer's pinned
                // latest pass. Unwrap under the data lock so a racing Weak upgrade
                // either pins the Arc we restore or observes its payload released.
                let released = match data.preview.take().map(Arc::try_unwrap) {
                    Some(Ok(preview)) => Some(preview),
                    Some(Err(preview)) => {
                        data.preview = Some(preview);
                        None
                    }
                    None => None,
                };
                drop(data);
                // Returning its lease locks the credit ledger; keep that outside
                // the status/publication lock before retrying the free slot.
                drop(released);
                reservation = credits.acquire()?;
                data = self.handle.0.data.lock().map_err(|_| JobError::new(ErrorCode::Internal, "render preview publication lock poisoned"))?;
                self.handle.0.cancel.check()?;
            }
            self.next_checkpoint_pass = self
                .next_checkpoint_pass
                .checked_add(1)
                .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "checkpoint pass ordinal exhausted"))?;
            let Some(reservation) = reservation else {
                data.preview_retention_skips = data
                    .preview_retention_skips
                    .checked_add(1)
                    .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "checkpoint retention diagnostic overflow"))?;
                return Ok(true);
            };
            data.preview = Some(Arc::new(RenderPreview {
                info: PreviewInfo {
                    frame_sequence,
                    samples_per_pixel,
                    adaptive: match self.handle.0.request.raytrace.as_ref().filter(|_| self.handle.0.request.integrator == Integrator::Raytrace) {
                        Some(options) => options
                            .adaptive
                            .as_deref()
                            .map(|adaptive| {
                                let maximum = options
                                    .progressive
                                    .ok_or_else(|| JobError::new(ErrorCode::Internal, "adaptive CPU preview has no captured film"))?
                                    .samples_per_pixel;
                                super::adaptive::AdaptivePreview::captured(*adaptive, maximum, samples_per_pixel)
                            })
                            .transpose()?,
                        None => super::adaptive::AdaptivePreview::at(self.handle.0.options()?, samples_per_pixel)?,
                    },
                    frame: info,
                },
                png,
                _reservation: reservation,
            }));
            self.next_preview_sequence = next_sequence;
            let pixels = u64::from(self.handle.0.request.width) * u64::from(self.handle.0.request.height);
            data.progress =
                Progress { phase: Phase::Running, done: pixels * u64::from(samples_per_pixel), total: pixels * u64::from(target_samples) };
            self.handle.0.notify();
            return Ok(true);
        }
        let exr = exr.map(|bytes| {
            let info = LinearMasterInfo {
                bytes: bytes.len() as u64,
                sha256: format!("{:x}", digest.finalize()),
                encoding: LinearColourEncoding::SceneLinearSrgbD65,
                alpha: LinearAlphaConvention::CoveragePremultiplied,
            };
            (bytes, info)
        });
        let retained = png.capacity() as u64 + exr.as_ref().map_or(0, |(bytes, _)| bytes.capacity() as u64) + FRAME_METADATA_BYTES;
        if let Some(credits) = &self.checkpoints {
            credits.close();
        }
        let mut reservation = self.reservation.take().ok_or_else(|| JobError::new(ErrorCode::Internal, "missing render reservation"))?;
        reservation.shrink(retained)?;
        data.frame = Some(Arc::new(RenderFrame {
            info,
            png,
            exr,
            source_master: self.source_master.take(),
            presentation: self.handle.0.presentation.clone(),
            _reservation: reservation,
        }));
        data.preview = None;
        data.progress = Progress { phase: Phase::Completed, done: 1, total: 1 };
        data.completed_duration = Some(self.handle.0.started.elapsed());
        self.handle.0.notify();
        Ok(false)
    }

    fn guarded_step(&mut self, units: usize) -> bool {
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.advance(units)));
        match result {
            Ok(Ok(more)) => more,
            Ok(Err(e)) => {
                terminal(&self.handle, e);
                false
            }
            Err(_) => {
                terminal(&self.handle, JobError::new(ErrorCode::Internal, "image host encountered an internal error"));
                false
            }
        }
    }
}

struct Shared {
    queue: Mutex<VecDeque<Work>>,
    active: Mutex<Option<Weak<Record>>>,
    stop: AtomicBool,
    budget: Arc<Budget>,
    #[cfg(not(target_arch = "wasm32"))]
    wake: Condvar,
}

struct Owner {
    executor: Option<Arc<dyn ImageExecutor>>,
    shared: Arc<Shared>,
    kind: HostKind,
    running: Mutex<Option<Running>>,
    #[cfg(not(target_arch = "wasm32"))]
    _worker: Option<std::thread::JoinHandle<()>>,
}

impl Drop for Owner {
    fn drop(&mut self) {
        self.shared.stop.store(true, Ordering::Release);
        if let Ok(active) = self.shared.active.lock()
            && let Some(record) = active.as_ref().and_then(Weak::upgrade)
        {
            let _ = JobHandle(record).cancel();
        }
        if let Ok(mut queue) = self.shared.queue.lock() {
            for work in queue.iter() {
                let _ = work.handle.cancel();
            }
            queue.clear();
        }
        if let Ok(mut running) = self.running.lock()
            && let Some(work) = running.take()
        {
            let _ = work.handle.cancel();
            terminal(&work.handle, JobError::new(ErrorCode::Cancelled, "render host closed"));
        }
        #[cfg(not(target_arch = "wasm32"))]
        self.shared.wake.notify_all();
        // Detaching cannot stall the UI; the bounded worker observes stop/cancel at its next unit.
    }
}

#[derive(Clone)]
pub struct ImageHost(Arc<Owner>);

/// Builtin CPU constructors share the registered image host lifetime machinery.
pub type CpuHost = ImageHost;

impl ImageHost {
    fn shared(limit: u64) -> Arc<Shared> {
        Arc::new(Shared {
            queue: Mutex::new(VecDeque::new()),
            active: Mutex::new(None),
            stop: AtomicBool::new(false),
            budget: Arc::new(Budget { used: AtomicU64::new(0), limit }),
            #[cfg(not(target_arch = "wasm32"))]
            wake: Condvar::new(),
        })
    }

    pub fn cooperative() -> Self {
        Self(Arc::new(Owner {
            executor: None,
            shared: Self::shared(MEMORY_LIMIT),
            kind: HostKind::Cooperative,
            running: Mutex::new(None),
            #[cfg(not(target_arch = "wasm32"))]
            _worker: None,
        }))
    }

    /// A cooperative host over `executor` (pumped by its caller).
    #[cfg(test)]
    fn cooperative_with(executor: Arc<dyn ImageExecutor>) -> Self {
        Self(Arc::new(Owner {
            executor: Some(executor),
            shared: Self::shared(MEMORY_LIMIT),
            kind: HostKind::Cooperative,
            running: Mutex::new(None),
            #[cfg(not(target_arch = "wasm32"))]
            _worker: None,
        }))
    }

    pub fn for_platform() -> Result<Self> {
        #[cfg(target_arch = "wasm32")]
        {
            Ok(Self::cooperative())
        }
        #[cfg(not(target_arch = "wasm32"))]
        {
            let pool = if usize::BITS >= 64 { super::NATIVE_CPU_POOL_BYTES } else { MEMORY_LIMIT };
            let shared = Self::shared(pool);
            let worker_shared = shared.clone();
            let worker = std::thread::Builder::new()
                .name("solidcraft-render".into())
                .spawn(move || native_worker(worker_shared))
                .map_err(|e| JobError::new(ErrorCode::HostUnavailable, format!("could not start CPU image worker: {e}")))?;
            Ok(Self(Arc::new(Owner { executor: None, shared, kind: HostKind::NativeWorker, running: Mutex::new(None), _worker: Some(worker) })))
        }
    }

    /// Start an isolated bounded native worker. GPU discovery occurs before registration.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn with_executor(executor: Arc<dyn ImageExecutor>) -> Result<Self> {
        let descriptor = executor.descriptor()?;
        if descriptor.profiles.len() != 1
            || descriptor
                .profiles
                .iter()
                .any(|p| p.mode != RenderMode::Preview || p.operation != RenderOperation::Image || p.formats != [RenderFormat::Png])
        {
            return Err(JobError::new(ErrorCode::InvalidRequest, "image worker currently accepts one Preview/Image/PNG profile"));
        }
        let limit = executor.memory_limit_bytes();
        let ceiling = if usize::BITS >= 64 { super::NATIVE_CPU_POOL_BYTES } else { MEMORY_LIMIT };
        if limit == 0 || limit > ceiling {
            return Err(JobError::new(ErrorCode::InvalidRequest, "registered image pool exceeds supported address space"));
        }
        let shared = Self::shared(limit);
        let worker_shared = shared.clone();
        let worker = std::thread::Builder::new()
            .name("solidcraft-render".into())
            .spawn(move || native_worker(worker_shared))
            .map_err(|e| JobError::new(ErrorCode::HostUnavailable, format!("could not start image worker: {e}")))?;
        Ok(Self(Arc::new(Owner { executor: Some(executor), shared, kind: HostKind::NativeWorker, running: Mutex::new(None), _worker: Some(worker) })))
    }

    pub fn kind(&self) -> HostKind {
        self.0.kind
    }

    pub fn same_host(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.0, &other.0)
    }
    pub fn is_available(&self) -> bool {
        !self.0.shared.stop.load(Ordering::Acquire)
    }
    pub fn admitted_bytes(&self) -> u64 {
        self.0.shared.budget.used.load(Ordering::Acquire)
    }

    /// Internal completed-film adapter: the existing host budget, no new pool.
    pub(crate) fn reserve_film_snapshot(&self, bytes: u64) -> Result<Reservation> {
        if self.0.executor.is_some() {
            return Err(JobError::new(ErrorCode::InvalidRequest, "CPU film snapshots require the builtin CPU host"));
        }
        if !self.is_available() {
            return Err(JobError::new(ErrorCode::HostUnavailable, "CPU image host has stopped"));
        }
        if bytes > super::image::MAX_JOB_BYTES {
            return Err(JobError::new(ErrorCode::LimitExceeded, "film snapshot exceeds per-job admission"));
        }
        self.0.shared.budget.reserve(bytes)
    }

    pub fn descriptor(&self) -> Result<ExecutorDescriptor> {
        self.descriptor_for(Integrator::Raster)
    }

    pub fn job_limit_bytes(&self) -> u64 {
        if self.0.executor.is_some() { self.0.shared.budget.limit } else { super::image::MAX_JOB_BYTES }
    }

    pub fn pool_limit_bytes(&self) -> u64 {
        self.0.shared.budget.limit
    }

    fn capture_retained_context(&self, retained: Option<&RetainedMetadata>) -> Result<Option<u64>> {
        if retained.is_some_and(|lease| !Arc::ptr_eq(&lease.0.budget, &self.0.shared.budget)) {
            return Err(JobError::new(ErrorCode::WrongOwner, "retained metadata belongs to a different host pool"));
        }
        Ok(retained.map(RetainedMetadata::bytes))
    }
    fn capture_descriptor(&self, profile: CaptureProfile) -> Result<ExecutorDescriptor> {
        if matches!(profile, CaptureProfile::Registered) != self.0.executor.is_some() {
            return Err(JobError::new(ErrorCode::WrongOwner, "capture profile does not match the installed host"));
        }
        self.validate_integrator(profile.integrator())?;
        if let CaptureProfile::CpuRaytrace(budget) = profile {
            budget.validate_execution()?;
        }
        let descriptor = self.descriptor_for(profile.integrator())?;
        if descriptor.availability != Availability::Available || descriptor.profiles.len() != 1 {
            return Err(JobError::new(ErrorCode::HostUnavailable, "capture executor is unavailable"));
        }
        Ok(descriptor)
    }
    /// Fund the next capture peak without a scene/request, fake job or renderer
    /// allocation. The independent Plan lease is counted, never transferred.
    pub fn reserve_capture<'a>(
        &self,
        bytes: u64,
        profile: CaptureProfile,
        cancel: &CancelToken,
        retained: Option<&'a RetainedMetadata>,
    ) -> Result<CaptureLease<'a>> {
        cancel.check()?;
        let mut descriptor = self.capture_descriptor(profile)?;
        let context = self.capture_retained_context(retained)?;
        self.check_request_sum(bytes, context.unwrap_or(0), profile.budget())?;
        let descriptor_hash = capture_fingerprint(&descriptor)?;
        // Resolution canonicalizes these enum lists. Pin its same value order
        // without cloning/allocating another profile or altering the raw hash.
        for profile in &mut descriptor.profiles {
            profile.formats.sort_unstable();
            profile.features.sort_unstable();
        }
        let execution = capture_fingerprint(&(&descriptor.id, descriptor.profiles.first()))?;
        let reservation = self.0.shared.budget.reserve(bytes)?;
        Ok(CaptureLease {
            host: self.clone(),
            profile,
            descriptor: descriptor_hash,
            execution,
            retained,
            cancel: cancel.clone(),
            reservation,
            consumed: false,
        })
    }

    /// Strict blocking API. Native UI callers prepare beside the window. The
    /// temporary lease exists before any new box proof backing is allocated.
    pub fn admit(&self, scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
        let admission = self.admit_layout(scene, request, options)?;
        #[cfg(feature = "raytrace-cpu")]
        if self.0.executor.is_none() && request.integrator == Integrator::Raytrace {
            let defaults = super::RaytraceOptions::default();
            let raytrace = request.raytrace.as_ref().unwrap_or(&defaults);
            let bytes = crate::raytrace::image::certification_bytes(scene, raytrace)?;
            if bytes != 0 {
                let _validation = self.0.shared.budget.reserve(bytes)?;
                crate::raytrace::image::certify_for_request(scene, request, raytrace, &CancelToken::default())?;
            }
        }
        Ok(admission)
    }

    fn admit_layout(&self, scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
        let scatter = |t: Option<crate::transmission::Transmission>| t.and_then(|v| v.subsurface()).is_some_and(|s| s.active());
        if scene.meshes.iter().any(|b| scatter(b.transmission) || b.faces.iter().any(|f| scatter(f.transmission)))
            && !self.0.executor.as_ref().is_some_and(|executor| executor.supports_subsurface())
        {
            return Err(JobError::new(ErrorCode::InvalidRequest, "installed image producer does not implement interior subsurface random walks"));
        }

        self.validate_integrator(request.integrator)?;
        options.validate()?;
        if let Some(executor) = &self.0.executor {
            let modeled = |t: Option<crate::transmission::Transmission>| t.is_some_and(|t| t.model().is_some());
            if scene.meshes.iter().any(|b| modeled(b.transmission) || b.faces.iter().any(|f| modeled(f.transmission)))
                && !executor.supports_glass_models()
            {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement the authored advanced Glass models"));
            }
            if options.caustics.is_some() && !executor.supports_caustics() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement delta-light caustic photons"));
            }
            if request.raytrace.is_some() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executors do not accept CPU raytrace options"));
            }
            if options.aging.active() && !executor.supports_aging() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "this executor cannot evaluate ordered surface aging"));
            }
            if options.finishing.photographic.active() && !executor.supports_photographic() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "this executor cannot apply photographic lens effects"));
            }
            if options.nested_media && !executor.supports_nested_media() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement certified nested media"));
            }
            if options.volume.is_some() && !executor.supports_volume() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement bounded homogeneous volume transport"));
            }
            if options.adaptive.is_some() && !executor.supports_adaptive_sampling() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement independent-pilot adaptive sampling"));
            }
            if options.transmission_samples != 1 && !executor.supports_transmission_sampling() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement transmission strata"));
            }
            if options.linear_exr && !executor.supports_linear_exr() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "this executor cannot retain a raw linear EXR"));
            }
            if options.finishing.bloom.is_some_and(|b| b.active()) && !executor.supports_bloom() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered executor does not implement display bloom"));
            }
            if (!options.finishing.is_identity() || options.backdrop.is_some()) && !executor.supports_finishing() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "this executor cannot apply the requested finishing/backdrop"));
            }
            let mut admission = executor.admit(scene, request, options)?;
            if let Some(samples) = executor.preview_samples(options) {
                if !(1..=options.preview_target()?).contains(&samples) {
                    return Err(JobError::new(ErrorCode::InvalidRequest, "executor preview target exceeds captured sampling passes"));
                }
                let slots = samples.saturating_sub(1).min(2);
                if slots != 0 {
                    let previews = admission
                        .encoded_limit
                        .checked_add(FRAME_METADATA_BYTES)
                        .and_then(|bytes| bytes.checked_mul(u64::from(slots)))
                        .and_then(|bytes| bytes.checked_add(FRAME_METADATA_BYTES))
                        .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "executor preview admission overflow"))?;
                    admission.estimated_total_bytes = admission
                        .estimated_total_bytes
                        .checked_add(previews)
                        .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "executor preview admission overflow"))?;
                }
            }
            if admission.estimated_total_bytes > self.job_limit_bytes() {
                return Err(JobError::new(ErrorCode::LimitExceeded, "registered image job exceeds its admitted host pool"));
            }
            Ok(admission)
        } else {
            request.cpu_budget().validate_execution()?;
            if options != JobOptions::default() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "CPU images use raytrace options, not progressive sampling controls"));
            }
            super::image::admit_layout(scene, request)
        }
    }

    fn check_request_sum(&self, work: u64, request: u64, budget: super::CpuBudget) -> Result<()> {
        if self.0.executor.is_none() {
            if budget == super::CpuBudget::Compact {
                return admit_request_sum(work, request);
            }
            if work.checked_add(request).is_none_or(|n| n > budget.limits().max_job_bytes) {
                return Err(JobError::new(ErrorCode::LimitExceeded, "CPU work and retained request exceed the selected profile"));
            }
            return Ok(());
        }
        if work.checked_add(request).is_none_or(|n| n > self.job_limit_bytes()) {
            return Err(JobError::new(ErrorCode::LimitExceeded, "registered image job exceeds its admitted host pool"));
        }
        Ok(())
    }

    /// Check the execution choice without capturing geometry or reserving memory.
    pub fn validate_integrator(&self, integrator: Integrator) -> Result<()> {
        if self.0.executor.is_some() && integrator != Integrator::Raster {
            return Err(JobError::new(ErrorCode::InvalidRequest, "registered image executors do not accept CPU raytrace requests"));
        }
        if !self.is_available() {
            return Err(JobError::new(ErrorCode::HostUnavailable, "image host has stopped"));
        }
        if integrator == Integrator::Raytrace && !cfg!(feature = "raytrace-cpu") {
            return Err(JobError::new(ErrorCode::HostUnavailable, "CPU raytracing is not compiled in; enable raytrace-cpu"));
        }
        if integrator == Integrator::Raytrace && self.kind() != HostKind::NativeWorker {
            return Err(JobError::new(ErrorCode::HostUnavailable, "CPU raytracing requires the native worker host"));
        }
        Ok(())
    }

    /// Select exactly one executor for this request. Never rely on registry order
    /// to choose between raster and raytracing implementations.
    pub fn descriptor_for(&self, integrator: Integrator) -> Result<ExecutorDescriptor> {
        if let Some(executor) = &self.0.executor {
            if integrator != Integrator::Raster {
                return Err(JobError::new(ErrorCode::InvalidRequest, "registered image executors do not accept CPU raytrace requests"));
            }
            let mut descriptor = executor.descriptor()?;
            if !self.is_available() {
                descriptor.availability = Availability::Unavailable { reason: "image host has stopped".into() };
            }
            return Ok(descriptor);
        }
        if integrator == Integrator::Raytrace && !cfg!(feature = "raytrace-cpu") {
            return Err(JobError::new(ErrorCode::HostUnavailable, "CPU raytracing is not compiled in; enable raytrace-cpu"));
        }
        Ok(ExecutorDescriptor {
            id: ExecutorId::new(match integrator {
                Integrator::Raster => "cpu-product",
                Integrator::Raytrace => "cpu-raytrace",
            })
            .map_err(|e| JobError::new(ErrorCode::Internal, e.to_string()))?,
            availability: if self.0.shared.stop.load(Ordering::Acquire) {
                Availability::Unavailable { reason: "image host has stopped".into() }
            } else if integrator == Integrator::Raytrace && self.kind() != HostKind::NativeWorker {
                Availability::Unavailable { reason: "CPU raytracing requires the native worker host".into() }
            } else {
                Availability::Available
            },
            profiles: vec![RenderProfile {
                mode: RenderMode::Preview,
                operation: RenderOperation::Image,
                formats: vec![RenderFormat::Png],
                features: if integrator == Integrator::Raytrace && cfg!(feature = "raytrace-cpu") && self.kind() == HostKind::NativeWorker {
                    // Refraction is the certified thin-sheet/axis-aligned-box CPU preview
                    // contract. Admission still refuses unsupported geometry and combinations.
                    vec![crate::RenderFeature::Pbr, crate::RenderFeature::Hdri, crate::RenderFeature::Refraction]
                } else {
                    vec![crate::RenderFeature::Pbr]
                },
            }],
            limits: if integrator == Integrator::Raytrace && self.kind() == HostKind::NativeWorker && usize::BITS >= 64 {
                super::CpuBudget::Workstation.image_limits(false)
            } else {
                RenderLimits::default()
            },
            scratch: ScratchLayout { sample_scale: 2, sample_bytes_per_pixel: 8, output_bytes_per_pixel: 8, encoding_bytes_per_pixel: 8 },
        })
    }

    /// Resolve a CPU request against its explicit envelope, never the largest advertised one.
    pub fn descriptor_for_request(&self, request: &ImageRequest) -> Result<ExecutorDescriptor> {
        let mut descriptor = self.descriptor_for(request.integrator)?;
        if self.0.executor.is_none() && request.integrator == Integrator::Raytrace {
            let budget = request.cpu_budget();
            budget.validate_execution()?;
            budget.validate_image(request.width, request.height, request.raytrace.as_ref().and_then(|o| o.progressive))?;
            descriptor.limits = budget.image_limits(request.raytrace.as_ref().is_some_and(|o| o.progressive.is_some()));
        }
        Ok(descriptor)
    }

    pub fn submit(&self, id: JobId, scene_generation: u64, scene: ProductScene, request: ImageRequest) -> Result<JobHandle> {
        self.submit_with_environment(id, scene_generation, scene, request, None)
    }

    /// Captured HDR ownership stays in work, never serialized/cloned into status.
    pub fn submit_with_environment(
        &self,
        id: JobId,
        scene_generation: u64,
        scene: ProductScene,
        request: ImageRequest,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
    ) -> Result<JobHandle> {
        self.submit_with_environment_and_options(id, scene_generation, scene, request, JobOptions::default(), environment)
    }

    pub fn submit_with_options(
        &self,
        id: JobId,
        scene_generation: u64,
        scene: ProductScene,
        request: ImageRequest,
        options: JobOptions,
    ) -> Result<JobHandle> {
        self.submit_with_environment_and_options(id, scene_generation, scene, request, options, None)
    }

    pub fn submit_with_environment_and_options(
        &self,
        id: JobId,
        scene_generation: u64,
        scene: ProductScene,
        request: ImageRequest,
        options: JobOptions,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
    ) -> Result<JobHandle> {
        if id.session == 0 || id.serial == 0 || id.generation == 0 {
            return Err(JobError::new(ErrorCode::InvalidRequest, "invalid render job identity"));
        }
        let prepared = self.prepare_submission(scene, request, options, environment, CancelToken::default())?;
        self.submit_prepared(id, scene_generation, prepared)
    }

    /// Strict captured preparation. All new certificate backing is reserved
    /// before allocation; the opaque capsule owns resources and leases to enqueue.
    pub fn prepare_submission(
        &self,
        scene: ProductScene,
        request: ImageRequest,
        options: JobOptions,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
        cancel: CancelToken,
    ) -> Result<PreparedSubmission> {
        self.prepare_submission_with_metadata(scene, request, options, environment, cancel, None)
    }
    /// The external owner already holds this independent same-pool lease. Count
    /// its simultaneous backing before certificate/renderer allocation, without
    /// reserving it twice or transferring its lifetime into Work.
    pub fn prepare_submission_with_metadata(
        &self,
        scene: ProductScene,
        request: ImageRequest,
        options: JobOptions,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
        cancel: CancelToken,
        retained: Option<&RetainedMetadata>,
    ) -> Result<PreparedSubmission> {
        self.prepare_submission_inner(scene, request, options, environment, cancel, retained, None)
    }
    /// Consume already-owned capture credit. On any inner refusal/unwind, its
    /// typed inputs drop before this outer lease. After PreparedSubmission owns
    /// those inputs, merge credit and use the original Work/request split.
    pub fn prepare_submission_with_capture(
        &self,
        scene: ProductScene,
        request: ImageRequest,
        options: JobOptions,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
        cancel: CancelToken,
        retained: Option<&RetainedMetadata>,
        mut capture: CaptureLease<'_>,
    ) -> Result<PreparedSubmission> {
        self.prepare_submission_inner(scene, request, options, environment, cancel, retained, Some(&mut capture))
    }
    fn prepare_submission_inner(
        &self,
        scene: ProductScene,
        request: ImageRequest,
        options: JobOptions,
        environment: Option<crate::lighting::environment_input::EnvironmentInput>,
        cancel: CancelToken,
        retained: Option<&RetainedMetadata>,
        capture: Option<&mut CaptureLease<'_>>,
    ) -> Result<PreparedSubmission> {
        if let Some(credit) = capture.as_deref() {
            credit.check_request(self, &request, &cancel, retained)?;
        }
        cancel.check()?;
        if retained.is_some_and(|lease| !Arc::ptr_eq(&lease.0.budget, &self.0.shared.budget)) {
            return Err(JobError::new(ErrorCode::WrongOwner, "retained metadata belongs to a different host pool"));
        }
        if !self.is_available() {
            return Err(JobError::new(ErrorCode::HostUnavailable, "image host has stopped"));
        }
        if self.0.executor.is_some() && environment.is_some() {
            return Err(JobError::new(ErrorCode::InvalidRequest, "registered image executors do not accept CPU environments"));
        }
        if environment.is_some() && request.integrator != Integrator::Raytrace {
            return Err(JobError::new(ErrorCode::InvalidRequest, "environment lighting requires CPU raytrace"));
        }
        self.validate_integrator(request.integrator)?;
        if environment.is_some() {
            request.raytrace.as_ref().unwrap_or(&super::RaytraceOptions::default()).validate_environment_reflections(&scene)?;
        }
        let environment_info = environment
            .as_ref()
            .map(|e| JobEnvironmentInfo::Cpu(e.metadata()))
            .or_else(|| request.environment.as_ref().map(|source| JobEnvironmentInfo::Gpu(source.info().clone())));
        let textures = request.textures.as_ref().map(|source| source.summary());
        let metadata_bytes =
            if environment.is_some() { std::mem::size_of::<crate::lighting::environment_input::EnvironmentInfo>() as u64 } else { 0 }
                + request.retained_resource_metadata_bytes();
        let request_bytes = retained_request_bytes(&request)?
            .checked_add(options.retained_bytes()?)
            .and_then(|bytes| bytes.checked_add(metadata_bytes))
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "environment metadata overflow"))?;
        let mut features = scene.required_features();
        if environment.is_some() || request.environment.is_some() {
            features.push(crate::RenderFeature::Hdri);
        }
        if request.integrator == Integrator::Raytrace
            && request.raytrace.as_ref().is_some_and(|options| !options.dielectrics.is_empty())
            && !features.contains(&crate::RenderFeature::Refraction)
        {
            features.push(crate::RenderFeature::Refraction);
        }
        let mut admission = self.admit_layout(&scene, &request, options)?;
        let estimated_total_bytes = admission.estimated_total_bytes;
        let environment_bytes =
            environment.as_ref().map_or(Ok(0), |e| e.required_bytes()).map_err(|e| JobError::new(ErrorCode::InvalidRequest, e.to_string()))?;
        let estimated_total_bytes = estimated_total_bytes
            .checked_add(environment_bytes)
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "environment admission overflow"))?;
        let simultaneous = request_bytes
            .checked_add(retained.map_or(0, RetainedMetadata::bytes))
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "retained preparation byte overflow"))?;
        self.check_request_sum(estimated_total_bytes, simultaneous, request.cpu_budget())?;
        let mut backend = crate::builtin_backend();
        let descriptor = self.descriptor_for_request(&request)?;
        if let Some(credit) = capture.as_deref()
            && credit.profile == CaptureProfile::Registered
            && capture_fingerprint(&descriptor)? != credit.descriptor
        {
            return Err(JobError::new(ErrorCode::HostUnavailable, "resolved capture executor metadata changed"));
        }
        let expected_executor = descriptor.id.clone();
        backend.executors = vec![descriptor];
        let resolved = crate::resolve_request(
            &[backend],
            &crate::RenderRequest {
                backend: None,
                mode: RenderMode::Preview,
                operation: RenderOperation::Image,
                width: u64::from(request.width),
                height: u64::from(request.height),
                format: Some(RenderFormat::Png),
                features,
                policy: Default::default(),
            },
        )
        .map_err(|e| JobError::new(ErrorCode::HostUnavailable, e.to_string()))?;
        if resolved.executor != expected_executor {
            return Err(JobError::new(ErrorCode::HostUnavailable, "CPU product executor is unavailable"));
        }
        // Reap cancelled queued captures on the preparation caller, before a
        // replacement competes for their still-held credit. Never hold this
        // lock while geometry is certified.
        {
            let mut queue = self.0.shared.queue.lock().map_err(|_| JobError::new(ErrorCode::HostUnavailable, "render queue lock poisoned"))?;
            queue.retain(|work| !work.handle.0.cancel.is_cancelled());
        }
        let combined_bytes = estimated_total_bytes
            .checked_add(request_bytes)
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "prepared work/request byte overflow"))?;
        if let Some(credit) = capture.as_deref()
            && capture_fingerprint(&(&resolved.executor, Some(&resolved.profile)))? != credit.execution
        {
            return Err(JobError::new(ErrorCode::WrongOwner, "resolved capture executor/profile changed"));
        }
        let already_held = capture.as_deref().map_or(0, CaptureLease::bytes);
        // A retired pending duplicate/validator can make capture's high-water
        // peak larger than the final renderer layout. Keep that conservative
        // excess in Work until release, and report it as preparation backing.
        // The independent Plan is still counted once under the same cap.
        if already_held > combined_bytes {
            self.check_request_sum(already_held, retained.map_or(0, RetainedMetadata::bytes), request.cpu_budget())?;
            let extra = already_held - combined_bytes;
            admission.preparation_bytes = admission
                .preparation_bytes
                .checked_add(extra)
                .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "capture preparation admission overflow"))?;
            admission.estimated_total_bytes = admission
                .estimated_total_bytes
                .checked_add(extra)
                .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "capture work admission overflow"))?;
        }
        let mut reservation = self.0.shared.budget.reserve(combined_bytes.saturating_sub(already_held))?;
        // The legacy None branch keeps its original debit and split. Captured
        // inputs first move under PreparedSubmission's drop order, while the
        // outer caller still owns already_held, before transfer/split can fail.
        let request_reservation = if capture.is_some() || request_bytes == 0 { None } else { Some(reservation.split(request_bytes)?) };
        // Preserve the original CPU option capacities in the retained request and its lease.
        // Registered executors and textured CPU jobs move resource Arcs into work
        // and keep a small public copy under the retained metadata lease.
        let (public_request, work_request) = if self.0.executor.is_some() || request.textures.is_some() {
            (ImageRequest { environment: None, textures: None, ..request.clone() }, Some(request))
        } else {
            (request, None)
        };

        // Move all captured ownership under fields that drop before the leases
        // before any remaining fallible certificate/options allocation.
        let mut prepared = PreparedSubmission {
            scene,
            public_request,
            work_request,
            options: None,
            environment,
            environment_info,
            textures,
            resolved,
            admission,
            cancel,
            #[cfg(feature = "raytrace-cpu")]
            proof: Vec::new(),
            request_reservation,
            reservation,
            host: self.clone(),
        };
        if let Some(credit) = capture {
            prepared.reservation.merge_from(&mut credit.reservation)?;
            credit.consumed = true;
            prepared.request_reservation = if request_bytes == 0 { None } else { Some(prepared.reservation.split(request_bytes)?) };
        }
        #[cfg(feature = "raytrace-cpu")]
        if self.0.executor.is_none() && prepared.request().integrator == Integrator::Raytrace {
            let captured = prepared.request();
            let defaults = super::RaytraceOptions::default();
            let raytrace = captured.raytrace.as_ref().unwrap_or(&defaults);
            if let Some(certified) = crate::raytrace::image::certify_for_request(&prepared.scene, captured, raytrace, &prepared.cancel)? {
                prepared
                    .proof
                    .try_reserve_exact(1)
                    .map_err(|_| JobError::new(ErrorCode::AllocationFailed, "could not retain certified optical result"))?;
                if prepared.proof.capacity() != 1 {
                    return Err(JobError::new(ErrorCode::LimitExceeded, "optical proof capacity exceeds admission"));
                }
                prepared.proof.push(certified);
            }
        }
        prepared.cancel.check()?;
        prepared.options = if options.is_structural_default() { None } else { Some(RetainedOptions::new(options)?) };
        Ok(prepared)
    }

    /// Bounded publication into the existing queue. The real owning Session
    /// supplies identity only after source/host revalidation; no proof is redrained.
    pub fn submit_prepared(&self, id: JobId, scene_generation: u64, prepared: PreparedSubmission) -> Result<JobHandle> {
        self.try_submit_prepared(id, scene_generation, &mut Some(prepared))
    }

    /// Non-consuming failure path for native completion. On refusal the caller
    /// retains the complete capsule and its leases for worker-side retirement.
    /// Success takes it once, after all fallible queue/identity checks.
    pub fn try_submit_prepared(&self, id: JobId, scene_generation: u64, slot: &mut Option<PreparedSubmission>) -> Result<JobHandle> {
        let prepared = slot.as_ref().ok_or_else(|| JobError::new(ErrorCode::InvalidRequest, "prepared render was already consumed"))?;
        if id.session == 0 || id.serial == 0 || id.generation == 0 {
            return Err(JobError::new(ErrorCode::InvalidRequest, "invalid render job identity"));
        }
        if !self.same_host(&prepared.host) {
            return Err(JobError::new(ErrorCode::WrongOwner, "prepared render belongs to a different installed host"));
        }
        prepared.cancel.check()?;
        let options = prepared.options()?;
        let mut queue = self.0.shared.queue.lock().map_err(|_| JobError::new(ErrorCode::HostUnavailable, "render queue lock poisoned"))?;
        if self.0.shared.stop.load(Ordering::Acquire) {
            return Err(JobError::new(ErrorCode::HostUnavailable, "image host has stopped"));
        }
        // Background preparation/worker owns cancelled capture retirement.
        // A racing cancellation may keep this bounded queue full until drain;
        // completion must not destroy large request/source backing on the UI.
        if queue.len() >= QUEUE_LIMIT {
            return Err(JobError::new(ErrorCode::QueueFull, "image queue is full"));
        }
        let prepared = slot.take().ok_or_else(|| JobError::new(ErrorCode::Internal, "prepared render vanished before enqueue"))?;
        let PreparedSubmission {
            scene,
            public_request,
            work_request,
            options: retained_options,
            environment,
            environment_info,
            textures,
            resolved,
            admission,
            cancel,
            #[cfg(feature = "raytrace-cpu")]
            proof,
            request_reservation,
            reservation,
            host: _,
        } = prepared;
        let handle = JobHandle(Arc::new(Record {
            work_released: AtomicBool::new(false),
            preview_unavailable_reason: self.0.executor.as_ref().and_then(|executor| executor.preview_unavailable_reason(options)),
            started: web_time::Instant::now(),
            presentation: None,
            textures,
            options: retained_options,
            environment: environment_info,
            _request_reservation: request_reservation,
            id,
            scene_generation,
            request: public_request,
            resolved,
            cancel,
            data: Mutex::new(Data {
                preview_retention_skips: 0,
                completed_duration: None,
                punctual_diagnostics: None,
                sampling: None,
                progress: Progress { phase: Phase::Queued, done: 0, total: 1 },
                error: None,
                frame: None,
                preview: None,
            }),
            #[cfg(not(target_arch = "wasm32"))]
            done: Condvar::new(),
        }));
        queue.push_back(Work {
            regrade: None,
            #[cfg(feature = "raytrace-cpu")]
            proof,
            request: work_request,
            executor: self.0.executor.clone(),
            scene,
            handle: handle.clone(),
            encoded_limit: admission.encoded_limit,
            reservation,
            environment,
            _work_release: WorkRelease(Arc::downgrade(&handle.0)),
        });
        drop(queue);
        #[cfg(not(target_arch = "wasm32"))]
        self.0.shared.wake.notify_one();
        Ok(handle)
    }

    /// Regrade the exact retained native master. No geometry, material, light or
    /// device work is submitted. The original frame and its lease remain shared.
    pub fn submit_regrade(&self, id: JobId, source: &JobHandle, presentation: super::presentation::Presentation) -> Result<JobHandle> {
        if id.session == 0 || id.serial == 0 || id.generation == 0 || id.session != source.id().session || id == source.id() {
            return Err(JobError::new(ErrorCode::WrongOwner, "regrade requires a new identity in the source document session"));
        }
        let frame = source.frame()?.ok_or_else(|| JobError::new(ErrorCode::NotCompleted, "regrade requires a completed frame"))?;
        let master = frame.master_source()?;
        let bytes = super::regrade::required_bytes(&master, presentation)?;
        let raw = master.linear_master_info().ok_or_else(|| JobError::new(ErrorCode::InvalidRequest, "raw master metadata is missing"))?;
        let origin = super::presentation::MasterPresentation {
            source_job: source.id(),
            master_job: master.info.job,
            master_sha256: raw.sha256.clone(),
            presentation,
            denoise_applied: false,
        };
        let options = JobOptions {
            finishing: presentation.finishing,
            backdrop: presentation.backdrop,
            exposure_ev: presentation.exposure_ev,
            tone_map: presentation.tone_map,
            ..Default::default()
        };
        let option_bytes = options.retained_bytes()?;
        let request_bytes = option_bytes
            .checked_add(ImageRequest::fixed_cpu_metadata_bytes())
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "master request metadata overflow"))?;
        let metadata_bytes = (std::mem::size_of::<RetainedPresentation>() + origin.master_sha256.capacity() + 32) as u64;
        if bytes.checked_add(metadata_bytes).and_then(|n| n.checked_add(request_bytes)).is_none_or(|n| n > self.job_limit_bytes()) {
            return Err(JobError::new(ErrorCode::LimitExceeded, "master presentation exceeds the installed host's resource budget"));
        }
        let limits = RenderLimits { max_scratch_bytes: self.job_limit_bytes(), ..super::GPU_PATH_LIMITS };
        let descriptor = ExecutorDescriptor {
            id: ExecutorId::new("linear-master").map_err(|e| JobError::new(ErrorCode::Internal, e.to_string()))?,
            availability: Availability::Available,
            profiles: vec![RenderProfile {
                mode: RenderMode::Preview,
                operation: RenderOperation::Image,
                formats: vec![RenderFormat::Png],
                features: Vec::new(),
            }],
            limits,
            scratch: ScratchLayout { sample_scale: 1, sample_bytes_per_pixel: 32, output_bytes_per_pixel: 8, encoding_bytes_per_pixel: 8 },
        };
        let mut backend = crate::builtin_backend();
        backend.executors = vec![descriptor];
        let resolved = crate::resolve_request(
            &[backend],
            &crate::RenderRequest {
                backend: None,
                mode: RenderMode::Preview,
                operation: RenderOperation::Image,
                width: u64::from(frame.info.width),
                height: u64::from(frame.info.height),
                format: Some(RenderFormat::Png),
                features: Vec::new(),
                policy: Default::default(),
            },
        )
        .map_err(|e| JobError::new(ErrorCode::InvalidRequest, e.to_string()))?;
        let request = ImageRequest {
            studio_weights: None,
            width: frame.info.width,
            height: frame.info.height,
            camera: source.0.request.camera,
            background: presentation.background,
            transparent_background: presentation.transparent_background,
            environment: None,
            textures: None,
            integrator: Integrator::Raster,
            raytrace: None,
        };
        let mut queue = self.0.shared.queue.lock().map_err(|_| JobError::new(ErrorCode::HostUnavailable, "render queue lock poisoned"))?;
        if self.0.shared.stop.load(Ordering::Acquire) {
            return Err(JobError::new(ErrorCode::HostUnavailable, "image host has stopped"));
        }
        queue.retain(|work| !work.handle.0.cancel.is_cancelled());
        if queue.len() >= QUEUE_LIMIT {
            return Err(JobError::new(ErrorCode::QueueFull, "image queue is full"));
        }
        let reservation = self.0.shared.budget.reserve(bytes)?;
        let metadata = self.0.shared.budget.reserve(metadata_bytes)?;
        let option_reservation = if request_bytes == 0 { None } else { Some(self.0.shared.budget.reserve(request_bytes)?) };
        let origin = Arc::new(RetainedPresentation { info: origin, _reservation: metadata });
        let handle = JobHandle(Arc::new(Record {
            work_released: AtomicBool::new(false),
            preview_unavailable_reason: None,
            started: web_time::Instant::now(),
            presentation: Some(origin),
            textures: None,
            options: if options.is_structural_default() { None } else { Some(RetainedOptions::new(options)?) },
            environment: None,
            _request_reservation: option_reservation,
            id,
            scene_generation: frame.info.scene_generation,
            request,
            resolved,
            cancel: CancelToken::default(),
            data: Mutex::new(Data {
                preview_retention_skips: 0,
                completed_duration: None,
                punctual_diagnostics: None,
                sampling: None,
                progress: Progress { phase: Phase::Queued, done: 0, total: 1 },
                error: None,
                frame: None,
                preview: None,
            }),
            #[cfg(not(target_arch = "wasm32"))]
            done: Condvar::new(),
        }));
        queue.push_back(Work {
            #[cfg(feature = "raytrace-cpu")]
            proof: Vec::new(),
            regrade: Some((master, presentation)),
            request: None,
            executor: None,
            environment: None,
            scene: ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY },
            handle: handle.clone(),
            // Regrades are final-only and never create checkpoint slots.
            encoded_limit: 0,
            reservation,
            _work_release: WorkRelease(Arc::downgrade(&handle.0)),
        });
        drop(queue);
        #[cfg(not(target_arch = "wasm32"))]
        self.0.shared.wake.notify_one();
        Ok(handle)
    }

    /// Cooperative callers pump a small quantum independently of polling a job's status.
    /// Native jobs run even when the UI is idle or a headless caller is not polling.
    pub fn pump(&self, units: usize) -> Result<bool> {
        if self.0.kind != HostKind::Cooperative {
            return Ok(false);
        }
        let mut running = self.0.running.lock().map_err(|_| JobError::new(ErrorCode::HostUnavailable, "cooperative host lock poisoned"))?;
        if running.is_none() {
            let work = self.0.shared.queue.lock().map_err(|_| JobError::new(ErrorCode::HostUnavailable, "render queue lock poisoned"))?.pop_front();
            if let Some(work) = work {
                *running = Running::begin(work);
            }
        }
        if let Some(work) = running.as_mut() {
            if let Ok(mut active) = self.0.shared.active.lock() {
                *active = Some(Arc::downgrade(&work.handle.0));
            }
            if !work.guarded_step(units) {
                *running = None;
                if let Ok(mut active) = self.0.shared.active.lock() {
                    *active = None;
                }
            }
        }
        Ok(running.is_some()
            || !self.0.shared.queue.lock().map_err(|_| JobError::new(ErrorCode::HostUnavailable, "render queue lock poisoned"))?.is_empty())
    }
}

#[cfg(not(target_arch = "wasm32"))]
fn native_worker(shared: Arc<Shared>) {
    loop {
        let mut queue = match shared.queue.lock() {
            Ok(q) => q,
            Err(_) => {
                shared.stop.store(true, Ordering::Release);
                return;
            }
        };
        while queue.is_empty() && !shared.stop.load(Ordering::Acquire) {
            queue = match shared.wake.wait(queue) {
                Ok(q) => q,
                Err(_) => {
                    shared.stop.store(true, Ordering::Release);
                    return;
                }
            };
        }
        if shared.stop.load(Ordering::Acquire) {
            return;
        }
        let work = queue.pop_front();
        drop(queue);
        let Some(mut running) = work.and_then(Running::begin) else {
            continue;
        };
        if let Ok(mut active) = shared.active.lock() {
            *active = Some(Arc::downgrade(&running.handle.0));
        }
        loop {
            if shared.stop.load(Ordering::Acquire) {
                let _ = running.handle.cancel();
            }
            if !running.guarded_step(4096) {
                break;
            }
        }
        if let Ok(mut active) = shared.active.lock() {
            *active = None;
        }
    }
}
#[cfg(test)]
mod retained_request_tests {
    use super::*;

    #[test]
    fn retained_native_options_charge_actual_single_capacity_only_for_structural_nondefaults() {
        assert_eq!(JobOptions::default().retained_bytes().unwrap(), 0);
        let explicit = JobOptions { lighting: Some(super::super::StudioLighting::default()), ..Default::default() };
        let expected = std::mem::size_of::<JobOptions>() as u64;
        assert_eq!(explicit.retained_bytes().unwrap(), expected);
        let slot = RetainedOptions::new(explicit).unwrap();
        assert_eq!(slot.0.capacity(), 1);
        assert_eq!(slot.0.len(), 1);
        assert_eq!(slot.0[0], explicit);
        assert_ne!(slot.0[0], JobOptions::default(), "Some(black studio) must not become an absent default studio");
        assert!(std::mem::size_of::<Option<RetainedOptions>>() <= std::mem::size_of::<JobOptions>());
        let mut vignette = JobOptions::default();
        vignette.finishing.vignette = -0.0;
        let mut grain = JobOptions::default();
        grain.finishing.photographic.grain = -0.0;
        for options in [JobOptions { exposure_ev: -0.0, ..Default::default() }, vignette, grain] {
            assert!(!options.is_structural_default());
            assert_eq!(options.retained_bytes().unwrap(), expected);
            assert_eq!(RetainedOptions::new(options).unwrap().0[0].exposure_ev.to_bits(), options.exposure_ev.to_bits());
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn retained_gpu_options_lease_survives_work_release_frame_eviction_and_cloned_handles() {
        struct OptionsExecutor;
        impl ImageExecutor for OptionsExecutor {
            fn descriptor(&self) -> Result<ExecutorDescriptor> {
                CpuExecutor.descriptor()
            }
            fn admit(&self, scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
                options.validate()?;
                admit(scene, request)
            }
            fn begin(&self, scene: ProductScene, request: ImageRequest, options: JobOptions, cancel: CancelToken) -> Result<Box<dyn ImageWork>> {
                options.validate()?;
                CpuExecutor.begin(scene, request, options, cancel)
            }
        }
        for options in [
            JobOptions::default(),
            JobOptions { exposure_ev: -0.0, ..Default::default() },
            JobOptions { lighting: Some(super::super::StudioLighting::default()), ..Default::default() },
        ] {
            let mut host = ImageHost::with_executor(Arc::new(OptionsExecutor)).unwrap();
            let mut image = request();
            image.integrator = Integrator::Raster;
            image.raytrace = None;
            let expected = options.retained_bytes().unwrap();
            let job = host
                .submit_with_options(
                    JobId { session: 901, serial: 1, generation: 1 },
                    1,
                    ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY },
                    image,
                    options,
                )
                .unwrap();
            assert_eq!(job.status().unwrap().options, options);
            assert_eq!(job.status().unwrap().options.exposure_ev.to_bits(), options.exposure_ev.to_bits());
            assert_eq!(job.0.options.is_some(), expected != 0);
            if let Some(slot) = &job.0.options {
                assert_eq!(slot.0.capacity() as u64 * std::mem::size_of::<JobOptions>() as u64, expected);
            }
            assert_eq!(job.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
            host.0.shared.stop.store(true, Ordering::Release);
            host.0.shared.wake.notify_all();
            Arc::get_mut(&mut host.0).unwrap()._worker.take().unwrap().join().unwrap();
            assert!(job.work_released());
            let frame = job.frame().unwrap().unwrap();
            let held = job.clone();
            assert!(Arc::ptr_eq(&held.0, &job.0));
            job.0.data.lock().unwrap().frame = None;
            drop(frame);
            assert_eq!(host.admitted_bytes(), expected + ImageRequest::fixed_cpu_metadata_bytes());
            assert_eq!(held.status().unwrap().options, options);
            drop(job);
            assert_eq!(host.admitted_bytes(), expected + ImageRequest::fixed_cpu_metadata_bytes());
            drop(held);
            assert_eq!(host.admitted_bytes(), 0);
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn cancelled_gpu_options_are_retained_once_without_work_or_frame_credit() {
        struct Pending(CancelToken);
        impl ImageWork for Pending {
            fn step(&mut self, _: usize) -> Result<TaskPoll> {
                self.0.check()?;
                Ok(TaskPoll::Pending(Progress { phase: Phase::Running, done: 0, total: 1 }))
            }
        }
        struct Executor(std::sync::mpsc::SyncSender<()>);
        impl ImageExecutor for Executor {
            fn descriptor(&self) -> Result<ExecutorDescriptor> {
                CpuExecutor.descriptor()
            }
            fn admit(&self, scene: &ProductScene, request: &ImageRequest, options: JobOptions) -> Result<Admission> {
                options.validate()?;
                admit(scene, request)
            }
            fn begin(&self, _: ProductScene, _: ImageRequest, _: JobOptions, cancel: CancelToken) -> Result<Box<dyn ImageWork>> {
                self.0.send(()).unwrap();
                Ok(Box::new(Pending(cancel)))
            }
        }
        let light = super::super::DirectionalLightOptions { direction: [0.0, 0.0, 2.0], color: [0.25, 0.5, 1.0], intensity: 0.0 };
        let options = JobOptions {
            lighting: Some(super::super::StudioLighting {
                directional_lights: super::super::DirectionalLights::new(&[light; 8]).unwrap(),
                ..Default::default()
            }),
            ..Default::default()
        };
        let (began, received) = std::sync::mpsc::sync_channel(1);
        let mut host = ImageHost::with_executor(Arc::new(Executor(began))).unwrap();
        let mut image = request();
        image.integrator = Integrator::Raster;
        image.raytrace = None;
        let job = host
            .submit_with_options(
                JobId { session: 902, serial: 1, generation: 1 },
                1,
                ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY },
                image,
                options,
            )
            .unwrap();
        // Raw worker-stop below does not drain Shared::queue (Owner::drop does).
        // Establish actual begin before cancellation so join proves this active
        // work has dropped, independently of native worker scheduling.
        received.recv_timeout(std::time::Duration::from_secs(60)).unwrap();
        job.cancel().unwrap();
        assert_eq!(job.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Cancelled);
        host.0.shared.stop.store(true, Ordering::Release);
        host.0.shared.wake.notify_all();
        Arc::get_mut(&mut host.0).unwrap()._worker.take().unwrap().join().unwrap();
        assert!(job.work_released());
        assert!(job.frame().unwrap().is_none());
        assert_eq!(job.status().unwrap().options, options);
        assert_eq!(host.admitted_bytes(), options.retained_bytes().unwrap() + ImageRequest::fixed_cpu_metadata_bytes());
        let held = job.clone();
        drop(job);
        assert_eq!(held.status().unwrap().options, options);
        drop(held);
        assert_eq!(host.admitted_bytes(), 0);
    }

    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn cpu_master_regrade_retains_exact_options_and_raw_bytes_under_separate_metadata_leases() {
        let mut host = CpuHost::for_platform().unwrap();
        let mut image = request();
        image.raytrace.as_mut().unwrap().output = Some(Box::new(super::super::OutputOptions { linear_exr: true, ..Default::default() }));
        let original = host
            .submit(
                JobId { session: 903, serial: 1, generation: 1 },
                1,
                ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY },
                image,
            )
            .unwrap();
        assert_eq!(original.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
        assert!(original.0.options.is_none(), "CPU transport options retain their existing request lease, not a second native options slot");
        let original_frame = original.frame().unwrap().unwrap();
        let presentation = super::super::presentation::Presentation { exposure_ev: 1.0, ..Default::default() };
        let derivative = host.submit_regrade(JobId { session: 903, serial: 2, generation: 2 }, &original, presentation).unwrap();
        assert_eq!(derivative.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
        host.0.shared.stop.store(true, Ordering::Release);
        host.0.shared.wake.notify_all();
        Arc::get_mut(&mut host.0).unwrap()._worker.take().unwrap().join().unwrap();
        let frame = derivative.frame().unwrap().unwrap();
        assert_eq!(frame.linear_exr().unwrap(), original_frame.linear_exr().unwrap());
        assert_eq!(derivative.status().unwrap().options.exposure_ev, 1.0);
        let option_bytes = derivative.0.options().unwrap().retained_bytes().unwrap();
        let request_bytes = option_bytes + ImageRequest::fixed_cpu_metadata_bytes();
        assert_eq!(derivative.0._request_reservation.as_ref().unwrap().bytes, request_bytes);
        let presentation_bytes = derivative.0.presentation.as_ref().unwrap()._reservation.bytes;
        derivative.0.data.lock().unwrap().frame = None;
        original.0.data.lock().unwrap().frame = None;
        drop(frame);
        drop(original_frame);
        drop(original);
        assert_eq!(host.admitted_bytes(), request_bytes + presentation_bytes);
        let held = derivative.clone();
        drop(derivative);
        assert_eq!(held.status().unwrap().options.exposure_ev, 1.0);
        drop(held);
        assert_eq!(host.admitted_bytes(), 0);
    }

    #[test]
    fn retained_emitters_bill_vector_and_original_name_capacities_in_same_pool() {
        let mut request = request();
        let mut name = String::with_capacity(256);
        name.push_str("fixture");
        let mut emissions = Vec::with_capacity(32);
        emissions.push(super::super::SurfaceEmission {
            body_index: 0,
            body: name,
            color: [1.0; 3],
            strength: 1.0,
            sides: super::super::EmissionSides::Front,
        });
        let options = request.raytrace.as_mut().unwrap();
        options.emissions = Some(emissions);
        let expected = 8 * std::mem::size_of::<super::super::DirectionalLightOptions>() as u64
            + 32 * std::mem::size_of::<super::super::SurfaceEmission>() as u64
            + 256;
        assert_eq!(retained_request_bytes(&request).unwrap(), expected);
        let budget = Arc::new(Budget { used: AtomicU64::new(0), limit: MEMORY_LIMIT });
        let lease = budget.reserve(expected).unwrap();
        assert_eq!(budget.used.load(Ordering::Acquire), expected);
        assert!(admit_request_sum(super::super::image::MAX_JOB_BYTES - expected, expected).is_ok());
        assert!(admit_request_sum(super::super::image::MAX_JOB_BYTES - expected + 1, expected).is_err());
        drop(lease);
        assert_eq!(budget.used.load(Ordering::Acquire), 0);
    }
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn emitter_request_lease_survives_real_completion_frame_eviction_and_last_handle() {
        let mut host = CpuHost::for_platform().unwrap();
        let mut request = request();
        let mut name = String::with_capacity(256);
        name.push_str("emitter");
        let mut values = Vec::with_capacity(32);
        values.push(super::super::SurfaceEmission {
            body_index: 0,
            body: name,
            color: [1.0; 3],
            strength: 1.0,
            sides: super::super::EmissionSides::Both,
        });
        request.raytrace.as_mut().unwrap().emissions = Some(values);
        let expected = retained_request_bytes(&request).unwrap() + request.retained_resource_metadata_bytes();
        let mesh = solidcraft_geom::Mesh {
            positions: vec![solidcore_record::Vec3::ZERO, solidcore_record::Vec3::X, solidcore_record::Vec3::Y],
            normals: vec![solidcore_record::Vec3::Z; 3],
            triangles: vec![[0, 1, 2]],
            tri_face: vec![0],
            ..Default::default()
        };
        let bounds = mesh.bounds();
        let scene = ProductScene {
            meshes: vec![crate::ProductMesh {
                transmission: None,
                name: "emitter".into(),
                mesh: Arc::new(mesh),
                color: [255; 3],
                opacity: 1.0,
                surface: None,
                faces: Vec::new(),
            }],
            bounds,
        };
        let job = host.submit(JobId { session: 1695, serial: 1, generation: 1 }, 1, scene, request).unwrap();
        assert_eq!(job.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
        // Completion publication precedes the worker's last temporary handle release.
        // Join this test's worker before asserting exact lease ownership, as in the union test.
        host.0.shared.stop.store(true, Ordering::Release);
        host.0.shared.wake.notify_all();
        Arc::get_mut(&mut host.0).unwrap()._worker.take().unwrap().join().unwrap();
        let frame = job.frame().unwrap().unwrap();
        let held = job.clone();
        job.0.data.lock().unwrap().frame = None;
        drop(job);
        assert!(host.admitted_bytes() > expected);
        drop(frame);
        assert_eq!(host.admitted_bytes(), expected);
        drop(held);
        assert_eq!(host.admitted_bytes(), 0);
    }
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    fn cpu_map_capture_fixture(mapped: bool, corrupt: bool) -> (ProductScene, ImageRequest, std::sync::Weak<Vec<u8>>) {
        use super::super::textures::{BaseColorMode, PlanarFrame, RuntimeTextures, TextureBinding, TextureMap};
        use image::ImageEncoder;
        use solidcore_record::Vec3;
        use solidcraft_geom::Mesh;
        let mut encoded = Vec::new();
        image::codecs::png::PngEncoder::new(&mut encoded).write_image(&[128, 64, 255, 255], 1, 1, image::ExtendedColorType::Rgba8).unwrap();
        if corrupt {
            let idat = encoded.windows(4).position(|w| w == b"IDAT").unwrap();
            encoded[idat + 4] ^= 0xff;
        }
        let map = TextureMap::new(encoded, crate::texture_input::MapRole::BaseColor).unwrap();
        let weak = map.source().encoded_weak();
        let surface = if mapped {
            Vec3::new(0.5, 0.5, 0.5)
        } else {
            let v = [128, 64, 255].map(|v| crate::surface::srgb8_to_linear(v) as f32 as f64);
            Vec3::new(v[0], v[1], v[2])
        };
        let mesh = Arc::new(Mesh {
            positions: vec![Vec3::new(-10.0, -10.0, 0.0), Vec3::new(10.0, -10.0, 0.0), Vec3::new(10.0, 10.0, 0.0), Vec3::new(-10.0, 10.0, 0.0)],
            normals: vec![Vec3::Z; 4],
            triangles: vec![[0, 1, 2], [0, 2, 3]],
            tri_face: vec![0; 2],
            ..Default::default()
        });
        let scene = ProductScene {
            bounds: mesh.bounds(),
            meshes: vec![crate::ProductMesh {
                name: "mapped".into(),
                mesh,
                color: [255; 3],
                opacity: 1.0,
                transmission: None,
                surface: Some(crate::surface::OpaqueSurface::new(surface, 0.0, 1.0, 1.0).unwrap()),
                faces: vec![],
            }],
        };
        let options = super::super::RaytraceOptions {
            lights: Some(vec![super::super::DirectionalLightOptions {
                direction: [0.0, 0.0, 1.0],
                color: [1.0; 3],
                intensity: std::f64::consts::PI,
            }]),
            progressive: Some(super::super::CpuProgressiveOptions { samples_per_pixel: 3, seed: 9 }),
            output: Some(Box::new(super::super::OutputOptions { linear_exr: true, ..Default::default() })),
            ..Default::default()
        };
        let request = ImageRequest {
            width: 1,
            height: 1,
            camera: crate::Camera { distance: 1.0, fov: 0.0, yaw: 0.0, pitch: std::f64::consts::FRAC_PI_2, ..Default::default() },
            background: [0; 3],
            transparent_background: false,
            integrator: Integrator::Raytrace,
            raytrace: Some(options),
            environment: None,
            studio_weights: None,
            textures: if mapped {
                Some(Arc::new(
                    RuntimeTextures::new(vec![TextureBinding {
                        body_index: 0,
                        body_name: "mapped".into(),
                        frame: PlanarFrame { origin: [0.0; 3], u: [100.0, 0.0, 0.0], v: [0.0, 100.0, 0.0] },
                        base_color: Some(map),
                        normal: None,
                        roughness: None,
                        metallic: None,
                        normal_strength: 1.0,
                        base_color_mode: BaseColorMode::Replace,
                        flip_v: false,
                    }])
                    .unwrap(),
                ))
            } else {
                None
            },
        };
        (scene, request, weak)
    }
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    fn cpu_map_manual_native_queue() -> ImageHost {
        // Deterministic queued/cancel/error boundary test using the real builtin
        // CPU factory and work leases; no substitute registered executor or render.
        ImageHost(Arc::new(Owner {
            executor: None,
            shared: ImageHost::shared(super::super::NATIVE_CPU_POOL_BYTES),
            kind: HostKind::NativeWorker,
            running: Mutex::new(None),
            _worker: None,
        }))
    }
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn cpu_map_native_factory_consumes_full_work_capture_and_releases_sources_before_retained_frames() {
        let (scene, request, weak) = cpu_map_capture_fixture(true, false);
        let mut host = ImageHost::for_platform().unwrap();
        let job = host.submit(JobId { session: 3301, serial: 1, generation: 1 }, 1, scene, request).unwrap();
        assert!(job.0.request.textures.is_none(), "Record must never retain a work-only texture Arc");
        let completed = job.wait_timeout(std::time::Duration::from_secs(60)).unwrap();
        assert_eq!(completed.progress.phase, Phase::Completed);
        assert_eq!(completed.textures.unwrap().bodies, 1);
        let (scene, request, _) = cpu_map_capture_fixture(false, false);
        let reference = host.submit(JobId { session: 3301, serial: 2, generation: 2 }, 1, scene, request).unwrap();
        assert_eq!(reference.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
        host.join_worker_for_test().unwrap();
        assert!(job.work_released());
        assert!(weak.upgrade().is_none(), "all original encoded Arcs drop even while job/frame handles survive");
        let frame = job.frame().unwrap().unwrap();
        let expected = reference.frame().unwrap().unwrap();
        assert_eq!(frame.png(), expected.png(), "builtin CPU factory must consume full Work.request, not stripped public metadata");
        assert_eq!(frame.linear_exr(), expected.linear_exr());
        assert!(frame.linear_exr().is_some());
        let color = [128, 64, 255].map(|v| {
            let x = crate::surface::srgb8_to_linear(v) as f32 as f64;
            solidcraft_geom::srgb::encode8(x / (1.0 + x))
        });
        assert_eq!(image::load_from_memory(frame.png()).unwrap().to_rgba8().get_pixel(0, 0).0, [color[0], color[1], color[2], 255]);
        let held = job.clone();
        job.0.data.lock().unwrap().frame = None;
        reference.0.data.lock().unwrap().frame = None;
        drop(frame);
        drop(expected);
        drop(job);
        assert!(weak.upgrade().is_none());
        drop(held);
        drop(reference);
        assert_eq!(host.admitted_bytes(), 0);
    }
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn cpu_map_queued_cancel_failed_decode_and_late_cancel_keep_full_work_barrier_and_no_publication() {
        for mode in ["queued_cancel", "failed_decode", "late_cancel"] {
            let host = cpu_map_manual_native_queue();
            let (scene, request, weak) = cpu_map_capture_fixture(true, mode == "failed_decode");
            let retained = retained_request_bytes(&request).unwrap() + request.retained_resource_metadata_bytes();
            let job = host.submit(JobId { session: 3302, serial: 1, generation: 1 }, 1, scene, request).unwrap();
            assert!(job.0.request.textures.is_none());
            assert!(weak.upgrade().is_some());
            let work = host.0.shared.queue.lock().unwrap().pop_front().unwrap();
            assert!(work.request.as_ref().unwrap().textures.is_some());
            if mode == "queued_cancel" {
                job.cancel().unwrap();
                assert!(!job.work_released());
                assert!(Running::begin(work).is_none());
            } else {
                let mut running = Running::begin(work).unwrap();
                let mut stopped = false;
                for _ in 0..200_000 {
                    if mode == "late_cancel" && running.pending_png.as_ref().is_some_and(|pending| pending.preview_samples.is_none()) {
                        job.cancel().unwrap();
                        assert!(!running.guarded_step(1));
                        stopped = true;
                        break;
                    }
                    if !running.guarded_step(1) {
                        stopped = true;
                        break;
                    }
                }
                assert!(stopped);
                assert!(!job.work_released(), "terminal phase cannot release an undropped work lease");
                drop(running);
            }
            assert!(job.work_released());
            assert!(weak.upgrade().is_none());
            let status = job.status().unwrap();
            assert_eq!(status.progress.phase, if mode == "failed_decode" { Phase::Failed } else { Phase::Cancelled });
            assert!(job.frame().unwrap().is_none());
            assert!(job.preview().unwrap().is_none());
            assert_eq!(host.admitted_bytes(), retained, "only exact small public request/summary ownership survives work release");
            let held = job.clone();
            drop(job);
            assert_eq!(host.admitted_bytes(), retained);
            drop(held);
            assert_eq!(host.admitted_bytes(), 0);
        }
    }

    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn cpu_map_source_and_peak_decode_prepaid_pool_refusal_releases_all_captures_before_queueing() {
        let (scene, request, weak) = cpu_map_capture_fixture(true, false);
        let admission = super::super::admit(&scene, &request).unwrap();
        let total = admission.estimated_total_bytes + retained_request_bytes(&request).unwrap() + request.retained_resource_metadata_bytes();
        let mut host = cpu_map_manual_native_queue();
        Arc::get_mut(&mut host.0).unwrap().shared = ImageHost::shared(total - 1);
        assert_eq!(host.submit(JobId { session: 3303, serial: 1, generation: 1 }, 1, scene, request).err().unwrap().code, ErrorCode::LimitExceeded);
        assert_eq!(host.admitted_bytes(), 0);
        assert!(host.0.shared.queue.lock().unwrap().is_empty());
        assert!(weak.upgrade().is_none(), "a failed prepaid capture cannot retain hidden encoded resources or queue a decoder");
    }

    fn request() -> ImageRequest {
        let mut lights = Vec::with_capacity(8);
        lights.push(super::super::DirectionalLightOptions { direction: [0.0, 0.0, 1.0], color: [1.0; 3], intensity: 1.0 });
        ImageRequest {
            studio_weights: None,
            environment: None,
            textures: None,
            integrator: Integrator::Raytrace,
            raytrace: Some(super::super::RaytraceOptions { lights: Some(lights), ..Default::default() }),
            camera: Default::default(),
            width: 8,
            height: 8,
            background: [0; 3],
            transparent_background: false,
        }
    }
    #[test]
    fn retained_lights_are_billed_by_original_capacity_and_sum_is_checked() {
        let request = request();
        let bytes = retained_request_bytes(&request).unwrap();
        assert_eq!(bytes, 8 * std::mem::size_of::<super::super::DirectionalLightOptions>() as u64);
        let cap = super::super::image::MAX_JOB_BYTES;
        assert!(admit_request_sum(cap - bytes, bytes).is_ok());
        assert_eq!(admit_request_sum(cap - bytes + 1, bytes).unwrap_err().code, ErrorCode::LimitExceeded);
        assert_eq!(admit_request_sum(u64::MAX, 1).unwrap_err().code, ErrorCode::LimitExceeded);
    }
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn retained_lights_keep_the_same_pool_lease_after_png_eviction() {
        let host = CpuHost::for_platform().unwrap();
        let request = request();
        let expected = retained_request_bytes(&request).unwrap() + request.retained_resource_metadata_bytes();
        let job = host
            .submit(
                JobId { session: 99, serial: 1, generation: 1 },
                1,
                ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY },
                request,
            )
            .unwrap();
        assert_eq!(job.wait_timeout(std::time::Duration::from_secs(60)).unwrap().progress.phase, Phase::Completed);
        let frame = job.frame().unwrap().unwrap();
        let held_bytes = host.admitted_bytes();
        assert!(held_bytes > expected);
        job.0.data.lock().unwrap().frame = None;
        assert_eq!(host.admitted_bytes(), held_bytes);
        drop(frame);
        assert_eq!(host.admitted_bytes(), expected);
        let held = job.clone();
        drop(job);
        assert_eq!(host.admitted_bytes(), expected);
        drop(held);
    }
}

#[cfg(all(test, feature = "raytrace-cpu", not(target_arch = "wasm32")))]
mod environment_metadata_lease_tests {
    use super::*;
    #[test]
    fn captured_environment_metadata_survives_png_eviction_without_source_bytes() {
        use crate::lighting::{
            HdrSource,
            environment_input::{EnvironmentInfo, EnvironmentInput},
        };
        let mut bytes = b"#?RADIANCE\nFORMAT=32-bit_rle_rgbe\nPRIMARIES=0.64 0.33 0.30 0.60 0.15 0.06 0.3127 0.3290\n\n-Y 2 +X 4\n".to_vec();
        for _ in 0..8 {
            bytes.extend_from_slice(&[128, 64, 32, 129]);
        }
        let input = EnvironmentInput::new(HdrSource::new(bytes).unwrap(), 0.5, 2.0, 16).unwrap();
        let metadata = input.metadata();
        let expected = std::mem::size_of::<EnvironmentInfo>() as u64 + ImageRequest::fixed_cpu_metadata_bytes();
        let mut host = CpuHost::for_platform().unwrap();
        let budget = host.0.shared.budget.clone();
        let request = ImageRequest {
            studio_weights: None,
            environment: None,
            textures: None,
            integrator: Integrator::Raytrace,
            raytrace: None,
            camera: Default::default(),
            width: 8,
            height: 8,
            background: [0; 3],
            transparent_background: false,
        };
        let job = host
            .submit_with_environment(
                JobId { session: 1693, serial: 7, generation: 1 },
                1,
                ProductScene { meshes: Vec::new(), bounds: solidcraft_geom::Aabb3::EMPTY },
                request,
                Some(input),
            )
            .unwrap();
        let status = job.wait_timeout(std::time::Duration::from_secs(60)).unwrap();
        assert_eq!(status.progress.phase, Phase::Completed);
        assert!(matches!(status.environment, Some(JobEnvironmentInfo::Cpu(info)) if info.source_sha256 == metadata.source_sha256));
        host.join_worker_for_test().unwrap();
        let frame = job.frame().unwrap().unwrap();
        job.0.data.lock().unwrap().frame = None;
        assert_eq!(host.admitted_bytes(), frame._reservation.bytes + expected);
        drop(frame);
        assert_eq!(host.admitted_bytes(), expected);
        drop(host);
        drop(job);
        assert_eq!(budget.used.load(Ordering::Acquire), 0);
    }
}

#[cfg(all(test, feature = "raytrace-cpu", not(target_arch = "wasm32")))]
mod surface_request_metadata_tests {
    use super::*;
    use solidcraft_geom::{Aabb3, Mesh};
    #[cfg(all(feature = "raytrace-cpu", not(target_arch = "wasm32")))]
    #[test]
    fn surface_request_lease_survives_completion_frame_eviction_and_held_handles() {
        use crate::{ProductMesh, surface_patterns::SurfaceEffect};
        use std::time::{Duration, Instant};
        fn settle(host: &CpuHost, expected: u64) {
            let deadline = Instant::now() + Duration::from_secs(10);
            while host.admitted_bytes() != expected && Instant::now() < deadline {
                std::thread::yield_now();
            }
            assert_eq!(host.admitted_bytes(), expected);
        }
        let mut host = CpuHost::for_platform().unwrap();
        let mut meshes = Vec::new();
        let mut effects = Vec::with_capacity(32);
        for index in 0..32 {
            let mut name = String::with_capacity(256);
            name.push_str(&format!("{index:03}"));
            name.push_str(&"x".repeat(253));
            assert_eq!(name.capacity(), 256);
            meshes.push(ProductMesh {
                transmission: None,
                name: name.clone(),
                mesh: Arc::new(Mesh::default()),
                color: [100; 3],
                opacity: 1.0,
                surface: None,
                faces: Vec::new(),
            });
            effects.push(SurfaceEffect {
                body: name,
                frame: Default::default(),
                repeat_mm: [20.0; 3],
                roughness_amplitude: 0.0,
                bump_amplitude_mm: 0.0,
            });
        }
        let scene = ProductScene { meshes, bounds: Aabb3 { min: solidcore_record::Vec3::ZERO, max: solidcore_record::Vec3::ZERO } };
        let mut request = request();
        request.integrator = Integrator::Raytrace;
        request.raytrace = Some(super::super::RaytraceOptions { surface_effects: Some(effects), ..Default::default() });
        let metadata = retained_request_bytes(&request).unwrap() + request.retained_resource_metadata_bytes();
        assert!(metadata >= 32 * 256);
        let mut oversized = request.clone();
        let mut overallocated = Vec::with_capacity(64);
        overallocated.extend(oversized.raytrace.as_mut().unwrap().surface_effects.take().unwrap());
        oversized.raytrace.as_mut().unwrap().surface_effects = Some(overallocated);
        assert!(host.submit(id(40, 1), 1, scene.clone(), oversized).is_err());
        assert_eq!(host.admitted_bytes(), 0);

        let job = host.submit(id(40, 2), 1, scene, request).unwrap();
        assert_eq!(job.wait_timeout(Duration::from_secs(10)).unwrap().progress.phase, Phase::Completed);
        // Wait for this host's last temporary worker handle before exact lease checks.
        host.0.shared.stop.store(true, Ordering::Release);
        host.0.shared.wake.notify_all();
        Arc::get_mut(&mut host.0).unwrap()._worker.take().unwrap().join().unwrap();
        let frame = job.frame().unwrap().unwrap();
        let png_bytes = frame._reservation.bytes;
        settle(&host, metadata + png_bytes);
        // Evict the record's frame under the same lock used by publication, while
        // an external frame and a cloned job handle retain their independent leases.
        job.0.data.lock().unwrap().frame = None;
        let held = job.clone();
        drop(job);
        assert_eq!(host.admitted_bytes(), metadata + png_bytes);
        drop(frame);
        settle(&host, metadata);
        assert_eq!(held.status().unwrap().request.raytrace.unwrap().surface_effects.unwrap().len(), 32);
        drop(held);
        settle(&host, 0);
    }

    fn request() -> ImageRequest {
        ImageRequest {
            studio_weights: None,
            environment: None,
            textures: None,
            integrator: Default::default(),
            raytrace: None,
            camera: Default::default(),
            width: 16,
            height: 16,
            background: [40, 80, 120],
            transparent_background: false,
        }
    }

    fn id(owner: u64, serial: u64) -> JobId {
        JobId { session: owner, serial, generation: serial }
    }
}