Skip to content

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

126 KB
Raw Blame
//! Opt-in opaque direct image integration; immutable world geometry, one host reservation.
use super::anisotropic_faces::{self, PlanarTarget};
use super::bvh::TraceCursor;
use super::dielectric::{self, Certificate, MAX_BOUNDARIES, MAX_OVERRIDES, MAX_PATHS};
use super::lighting::{DirectionalLight, Lighting, StudioPreset, map_to_display};
use super::prepared::{PreparedPrimitive, PreparedScene, SharedHit};
#[cfg(test)]
use super::progressive;
use super::progressive::{CameraFilm, Progressive};
use super::reflection;
use super::{BuildLimits, Bvh, BvhBuilder, Ray, TraceError, Triangle, WorkBudget};
use crate::job::{self, Admission, CancelToken, ErrorCode, ImageRequest, JobError, Phase, Progress, RaytraceOptions, TaskPoll};
use crate::{
    ProductScene,
    surface::{OpaqueSurface, srgb8_to_linear},
};
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
use solidcraft_geom::srgb::encode8;

#[cfg(test)]
#[path = "environment_image_tests.rs"]
mod environment_image_tests;

#[cfg(test)]
#[path = "environment_reflection_tests.rs"]
mod environment_reflection_tests;

#[cfg(test)]
#[path = "anisotropic_reflection_image_tests.rs"]
mod anisotropic_reflection_tests;

pub(crate) fn error(e: TraceError) -> JobError {
    let code = match e {
        TraceError::Cancelled => ErrorCode::Cancelled,
        TraceError::MemoryLimit | TraceError::WorkLimit => ErrorCode::LimitExceeded,
        TraceError::AllocationFailed => ErrorCode::AllocationFailed,
        TraceError::InvalidInput(_) => ErrorCode::InvalidScene,
        _ => ErrorCode::Internal,
    };
    JobError::new(code, e.to_string())
}
pub(super) fn invalid(message: &'static str) -> JobError {
    JobError::new(ErrorCode::InvalidScene, message)
}
fn limits(budget: job::CpuBudget) -> BuildLimits {
    let limits = budget.limits();
    BuildLimits {
        max_triangles: limits.max_triangles as usize,
        max_memory_bytes: limits.max_job_bytes,
        max_work: limits.max_work_units,
        ..Default::default()
    }
}
fn lighting(options: &RaytraceOptions) -> job::Result<Lighting> {
    options.validate()?;
    if let Some(preset) = options.preset {
        let preset = match preset {
            job::LightingPreset::Neutral => StudioPreset::Neutral,
            job::LightingPreset::WarmCool => StudioPreset::WarmCool,
            job::LightingPreset::KeyRim => StudioPreset::KeyRim,
        };
        return Lighting::preset(preset).map_err(error);
    }
    match &options.lights {
        None => Ok(Lighting::studio_default()),
        Some(inputs) => {
            let mut lights = Vec::new();
            lights.try_reserve_exact(inputs.len()).map_err(|_| error(TraceError::AllocationFailed))?;
            for l in inputs {
                lights.push(
                    DirectionalLight::new(
                        Vec3::new(l.direction[0], l.direction[1], l.direction[2]),
                        Vec3::new(l.color[0], l.color[1], l.color[2]),
                        l.intensity,
                    )
                    .map_err(error)?,
                );
            }
            Lighting::new(lights).map_err(error)
        }
    }
}
type Look = PreparedPrimitive;

/// Sealed optical result transferred only with its owning captured scene/request.
/// The general cursor retains its exact certified f64 boundary and allocations;
/// moving it into ImageTask does not certify the same geometry a second time.
pub(crate) struct CertifiedOptics {
    legacy: Option<[Option<dielectric::Certificate>; MAX_OVERRIDES]>,
    general: Vec<super::glass_mesh::Task>,
    work_used: u64,
}
impl CertifiedOptics {
    pub(super) fn work_used(&self) -> u64 {
        self.work_used
    }
    pub(super) fn legacy(values: [Option<dielectric::Certificate>; MAX_OVERRIDES], work_used: u64) -> Self {
        Self { legacy: Some(values), general: Vec::new(), work_used }
    }
    fn into_legacy(self) -> job::Result<[Option<dielectric::Certificate>; MAX_OVERRIDES]> {
        if !self.general.is_empty() {
            return Err(invalid("unexpected general optical proof"));
        }
        self.legacy.ok_or_else(|| invalid("missing legacy optical proof"))
    }
}

pub(crate) fn certification_bytes(scene: &ProductScene, options: &RaytraceOptions) -> job::Result<u64> {
    if options.dielectrics.is_empty() {
        return Ok(0);
    }
    let bytes = if options.path.is_some() {
        super::glass_mesh::Task::required_bytes(scene, options)?
    } else {
        super::legacy_certificates::Task::required_bytes(scene, options).map_err(error)?
    };
    bytes.checked_add(std::mem::size_of::<CertifiedOptics>() as u64).ok_or_else(|| error(TraceError::MemoryLimit))
}

fn legacy_error(cause: TraceError) -> JobError {
    match cause {
        TraceError::InvalidInput(
            message @ ("nested, touching or overlapping dielectric volumes are unsupported"
            | "thin sheets touching or inside dielectric volumes are unsupported"
            | "thin-lens aperture sphere touches or enters a certified dielectric volume"),
        ) => invalid(message),
        other => error(other),
    }
}

pub(crate) fn certify_for_request(
    scene: &ProductScene,
    request: &ImageRequest,
    options: &RaytraceOptions,
    cancel: &CancelToken,
) -> job::Result<Option<CertifiedOptics>> {
    if options.dielectrics.is_empty() {
        cancel.check()?;
        return Ok(None);
    }
    cancel.check()?;
    if options.path.is_some() {
        let mut general = Vec::new();
        general.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
        if general.capacity() != 1 {
            return Err(error(TraceError::MemoryLimit));
        }
        let mut task = super::glass_mesh::Task::new(scene, options)?;
        let mut work = WorkBudget::new(options.budget.limits().max_work_units).map_err(error)?;
        while !task.ready() {
            task.step(scene, options, &mut work, cancel)?;
        }
        general.push(task);
        return Ok(Some(CertifiedOptics { legacy: None, general, work_used: work.used() }));
    }
    let mut task = super::legacy_certificates::Task::new(scene, request, options).map_err(error)?;
    let mut work = WorkBudget::new(options.budget.limits().max_work_units).map_err(error)?;
    while !task.ready() {
        task.step(scene, options, &mut work, cancel).map_err(legacy_error)?;
    }
    // The ordinary image continuation charges the same final proof store.
    work.tick(cancel).map_err(error)?;
    task.into_proof(work.used()).map(Some).map_err(error)
}

/// Strict blocking admission for standalone callers. Native UI preparation must
/// run it beside the window; a header check is never reported as full preflight.
pub fn admit(scene: &ProductScene, request: &ImageRequest, options: &RaytraceOptions) -> job::Result<Admission> {
    let admission = admit_layout(scene, request, options)?;
    if !options.dielectrics.is_empty() {
        certify_for_request(scene, request, options, &CancelToken::default())?;
    }
    Ok(admission)
}

pub(crate) fn admit_layout(scene: &ProductScene, request: &ImageRequest, options: &RaytraceOptions) -> job::Result<Admission> {
    options.validate()?;
    if let Some(original) = &request.raytrace {
        original.validate()?;
    }
    if request.raytrace.as_ref().unwrap_or(&RaytraceOptions::default()) != options {
        return Err(JobError::new(ErrorCode::InvalidRequest, "raytrace options disagree with image request"));
    }
    if request.integrator != job::Integrator::Raytrace {
        return Err(JobError::new(ErrorCode::InvalidRequest, "raytrace task requires raytrace integrator"));
    }
    if options.path.is_some() && scene.has_transmission() {
        return Err(invalid(if options.volume.as_ref().is_some_and(|v| v.active()) {
            "CPU Atmosphere cannot combine with captured Glass or subsurface scattering"
        } else {
            "CPU opaque path transport cannot discard authored transmission; choose its existing optical transport"
        }));
    }
    if let Some(output) = &options.output {
        output.presentation(options.exposure_ev, request.background, request.transparent_background).validate()?;
    }
    options.budget.validate_image(request.width, request.height, options.camera_sampling()?)?;
    if let Some(lens) = options.lens {
        lens.validate_camera(&request.camera)?;
    }
    if options.denoise {
        job::validate_cpu_denoise_image(request.width, request.height)?;
    }
    super::aging::validate_scene(scene, options)?;
    let map_bytes =
        request.textures.as_ref().map_or(Ok(0), |maps| job::textures::cpu_cache::CpuTextureCache::required_bytes(maps, scene, options))?;
    let mut a = job::image::admit_raytrace_source(scene, request, options.budget)?;
    if let Some(lens) = options.lens.filter(|lens| lens.aperture_radius_mm > 0.0) {
        // Bound every possible pupil/pixel ray against the same captured clip
        // interval used by ImageTask, before allocating or starting transport.
        let camera = &request.camera;
        let radius = if scene.meshes.is_empty() { 10.0 } else { scene.bounds.diagonal().max(10.0) + scene.bounds.center().dist(camera.target) };
        let clip = camera.clip(radius);
        let slope = (camera.half_height() / camera.distance) * (f64::from(request.width) / f64::from(request.height)).hypot(1.0)
            + lens.aperture_radius_mm / lens.focus_distance_mm;
        let scale = slope.hypot(1.0);
        let eye = camera.eye();
        let origin_bound = eye.x.abs().max(eye.y.abs()).max(eye.z.abs()) + lens.aperture_radius_mm + clip.0.abs() * scale;
        if !scale.is_finite()
            || !origin_bound.is_finite()
            || origin_bound > super::MAX_COORDINATE_MM
            || (clip.1 - clip.0) * scale > super::MAX_DISTANCE_MM
        {
            return Err(JobError::new(ErrorCode::InvalidRequest, "CPU thin-lens pupil exceeds the bounded ray coordinate or interval envelope"));
        }
    }
    let r = options.reflections.as_ref().filter(|r| !r.bodies.is_empty()).map_or(1, |r| r.samples);
    u64::from(request.width)
        .checked_mul(u64::from(request.height))
        .and_then(|n| n.checked_mul(u64::from(options.primary_samples)))
        .and_then(|n| n.checked_mul(u64::from(r)))
        .ok_or_else(|| invalid("spatial attempt count overflow"))?;
    for (index, body) in scene.meshes.iter().enumerate() {
        if body.opacity != 1.0 || body.faces.iter().any(|f| f.opacity != 1.0) {
            return Err(invalid("raytrace requires opaque body and face appearances"));
        }
        let has_coat = body.surface.is_some_and(|surface| surface.clear_coat().is_some())
            || body.faces.iter().any(|face| face.surface.is_some_and(|surface| surface.clear_coat().is_some()));
        let selected_transport = options.reflections.as_ref().is_some_and(|r| r.bodies.iter().any(|entry| entry.body == body.name))
            || options.anisotropic_faces.iter().flatten().any(|entry| entry.body_index == index)
            || options.dielectrics.iter().any(|entry| entry.body_index == index);
        if has_coat && selected_transport {
            return Err(invalid("CPU reflection, anisotropy and dielectric overrides do not support clear-coat transport"));
        }
    }
    if let Some(reflections) = &options.reflections {
        for override_ in &reflections.bodies {
            let count = scene.meshes.iter().filter(|body| body.name == override_.body).count();
            if count != 1 {
                return Err(JobError::new(ErrorCode::InvalidRequest, "reflection body must resolve to exactly one captured body"));
            }
        }
    }
    anisotropic_faces::prepare(scene, options, || Ok(()))?;
    for input in &options.dielectrics {
        if options.reflections.as_ref().is_some_and(|r| r.bodies.iter().any(|v| v.body == input.body_name))
            || options.anisotropic_faces.iter().flatten().any(|v| v.body_index == input.body_index)
            || options.emissions.iter().flatten().any(|v| v.body_index == input.body_index)
        {
            return Err(invalid("dielectric boundaries cannot also select opaque reflection, anisotropy or emission"));
        }
        if let Some(values) = &options.surface_effects {
            for value in values.iter().filter(|v| v.body == input.body_name) {
                if !value.prepare()?.is_identity() {
                    return Err(invalid("nonidentity surface effects on dielectric boundaries are unsupported"));
                }
            }
        }
    }
    if let Some(values) = &options.surface_effects {
        for value in values {
            let mut bodies = scene.meshes.iter().enumerate().filter(|(_, body)| body.name == value.body);
            let (index, _) = bodies.next().ok_or_else(|| JobError::new(ErrorCode::InvalidRequest, "surface effect body missing"))?;
            if bodies.next().is_some() {
                return Err(JobError::new(ErrorCode::InvalidRequest, "surface effect body must resolve uniquely"));
            }
            if !value.prepare()?.is_identity() && options.anisotropic_faces.iter().flatten().any(|target| target.body_index == index) {
                return Err(JobError::new(ErrorCode::InvalidRequest, "surface effects on a certified anisotropic body are not supported"));
            }
        }
    }
    if let Some(values) = &options.emissions {
        for value in values {
            if scene.meshes.get(value.body_index).is_none_or(|body| body.name != value.body) {
                return Err(invalid("surface emission target does not match captured body index and name"));
            }
        }
    }
    // Bill each task-owned options copy and the prepared emission vector in addition
    // to the unchanged baseline estimate. Record metadata has its independent lease.
    let emission_bytes = options
        .retained_emission_bytes()?
        .checked_add(request.raytrace.as_ref().map_or(Ok(0), RaytraceOptions::retained_emission_bytes)?)
        .and_then(|v| {
            v.checked_add(options.emissions.as_ref().map_or(0, Vec::len) as u64 * std::mem::size_of::<(usize, super::emission::Emission)>() as u64)
        })
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    // The task owns two independent options copies plus its prepared effect vector.
    // The original request Record remains billed by the same retained_bytes sum.
    let effect_bytes = options
        .retained_surface_effect_bytes()?
        .checked_add(request.raytrace.as_ref().map_or(Ok(0), RaytraceOptions::retained_surface_effect_bytes)?)
        .and_then(|v| {
            v.checked_add(
                options.surface_effects.as_ref().map_or(0, Vec::len) as u64
                    * std::mem::size_of::<(usize, crate::surface_patterns::PreparedEffect)>() as u64,
            )
        })
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    let legacy_bytes = if options.dielectrics.is_empty() || options.path.is_some() {
        0
    } else {
        certification_bytes(scene, options)?.checked_add(std::mem::size_of::<OpticalTask>() as u64).ok_or_else(|| error(TraceError::MemoryLimit))?
    };
    let optical_bytes = options
        .retained_dielectric_bytes()?
        .checked_add(request.raytrace.as_ref().map_or(Ok(0), RaytraceOptions::retained_dielectric_bytes)?)
        .and_then(|bytes| bytes.checked_add(legacy_bytes))
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    let aging_bytes = options
        .retained_aging_bytes()?
        .checked_add(request.raytrace.as_ref().map_or(Ok(0), RaytraceOptions::retained_aging_bytes)?)
        .and_then(|v| {
            v.checked_add(if options.aging.as_deref().is_some_and(job::aging::AgingStack::active) { super::aging::Task::required_bytes() } else { 0 })
        })
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    let adaptive_bytes = options
        .retained_adaptive_bytes()?
        .checked_add(request.raytrace.as_ref().map_or(Ok(0), RaytraceOptions::retained_adaptive_bytes)?)
        .and_then(|v| v.checked_add(if options.adaptive.is_some() { std::mem::size_of::<job::adaptive::SamplingReport>() as u64 } else { 0 }))
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    let celestial_bytes = options
        .retained_celestial_bytes()?
        .checked_add(request.raytrace.as_ref().map_or(Ok(0), RaytraceOptions::retained_celestial_bytes)?)
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    let n = usize::try_from(a.triangles).map_err(|_| error(TraceError::MemoryLimit))?;
    let film_bytes = if let Some(progressive) = options.progressive {
        let checkpoint = a.encoded_limit.checked_add(job::FRAME_METADATA_BYTES).ok_or_else(|| error(TraceError::MemoryLimit))?;
        CameraFilm::required_bytes(request.width, request.height, progressive, options.adaptive.as_deref(), options.budget)?
            .checked_add(u64::from(progressive.preview_slots()).checked_mul(checkpoint).ok_or_else(|| error(TraceError::MemoryLimit))?)
            .and_then(|v| v.checked_add(if progressive.preview_slots() == 0 { 0 } else { job::FRAME_METADATA_BYTES }))
            .and_then(|v| v.checked_add(std::mem::size_of::<Progressive>() as u64))
            .ok_or_else(|| error(TraceError::MemoryLimit))?
    } else {
        0
    };
    let output_bytes = options.output.as_deref().map_or(Ok(0), |output| {
        output
            .required_bytes(request.width, request.height)?
            .checked_add(2 * std::mem::size_of::<job::OutputOptions>() as u64)
            .ok_or_else(|| error(TraceError::MemoryLimit))
    })?;
    // Guides remain job-owned across all checkpoints. Two colour vectors are
    // required even with identity presentation; the normal output estimate already
    // pays for one when presentation or EXR is enabled.
    let denoise_bytes = if options.denoise {
        let pixels = u64::from(request.width) * u64::from(request.height);
        let output_already_paid = options.output.as_deref().is_some_and(|output| !output.identity_display() || output.linear_exr);
        super::denoise::Guides::required_bytes(request.width, request.height)?
            .checked_add(pixels.checked_mul(if output_already_paid { 16 } else { 32 }).ok_or_else(|| error(TraceError::MemoryLimit))?)
            .and_then(|v| v.checked_add(if output_already_paid { 0 } else { std::mem::size_of::<job::output::OutputTask>() as u64 }))
            .ok_or_else(|| error(TraceError::MemoryLimit))?
    } else {
        0
    };
    let general_glass_bytes = if options.path.is_some() && !options.dielectrics.is_empty() {
        certification_bytes(scene, options)?.checked_add(super::origin::Task::required_bytes()).ok_or_else(|| error(TraceError::MemoryLimit))?
    } else {
        0
    };
    let caustics_bytes = options.caustics.map_or(Ok(0), caustics::Task::required_bytes)?;
    let extra = BvhBuilder::required_bytes(n, n, limits(options.budget))
        .map_err(error)?
        .checked_add(a.triangles.checked_mul(std::mem::size_of::<Look>() as u64).ok_or_else(|| error(TraceError::MemoryLimit))?)
        .and_then(|v| v.checked_add(emission_bytes))
        .and_then(|v| v.checked_add(effect_bytes))
        .and_then(|v| v.checked_add(map_bytes))
        .and_then(|v| v.checked_add(aging_bytes))
        .and_then(|v| v.checked_add(optical_bytes))
        .and_then(|v| v.checked_add(general_glass_bytes))
        .and_then(|v| v.checked_add(caustics_bytes))
        .and_then(|v| v.checked_add(if options.path.is_some() { std::mem::size_of::<indirect_image::State>() as u64 } else { 0 }))
        .and_then(|v| v.checked_add(film_bytes))
        .and_then(|v| v.checked_add(adaptive_bytes))
        .and_then(|v| v.checked_add(celestial_bytes))
        .and_then(|v| v.checked_add(output_bytes))
        .and_then(|v| v.checked_add(denoise_bytes))
        // The resumable pixel owns two traversal cursors. Its fallible, fixed
        // heap slot is additional to the unchanged host/task-state allowance.
        .and_then(|v| v.checked_add(PendingPixelSlot::required_bytes()))
        .and_then(|v| {
            v.checked_add(8192 + if options.reflections.is_some() || options.anisotropic_faces.iter().any(Option::is_some) { 32768 } else { 0 })
        })
        .and_then(|v| {
            v.checked_add(options.area_lights.as_ref().map_or(0, Vec::capacity) as u64 * std::mem::size_of::<job::RectangleLightOptions>() as u64)
        })
        .and_then(|v| {
            v.checked_add(options.punctual_lights.as_ref().map_or(0, Vec::capacity) as u64 * std::mem::size_of::<job::PunctualLightOptions>() as u64)
        })
        .ok_or_else(|| error(TraceError::MemoryLimit))?;
    // Keep the conservative raster pixel/codec estimate; add every new owned buffer.
    a.preparation_bytes = a.preparation_bytes.checked_add(extra).ok_or_else(|| error(TraceError::MemoryLimit))?;
    a.estimated_total_bytes = a.estimated_total_bytes.checked_add(extra).ok_or_else(|| error(TraceError::MemoryLimit))?;
    if a.estimated_total_bytes > options.budget.limits().max_job_bytes {
        return Err(error(TraceError::MemoryLimit));
    }
    Ok(a)
}

struct PendingPixel {
    surface_cursor: usize,
    surface_index: Option<usize>,
    surface_ready: bool,
    emission_cursor: usize,
    punctual_index: usize,
    punctual_shadow: bool,
    punctual_ready: bool,
    punctual_value: Vec3,
    area_light: usize,
    area_index: u32,
    area_shadow: bool,
    area_ready: bool,
    area_value: Vec3,

    /// Proof from the primary generator, revoked for any selected reflector.
    /// A jittered/time-varying primary generator MUST supply false.
    repeatable_primary: bool,
    environment_sample: u32,
    environment_sum: Vec3,
    environment_cursor: Option<TraceCursor>,
    environment_value: Vec3,
    ray: Ray,
    cursor: TraceCursor,
    hit: Option<super::Hit>,
    visibility: [bool; 8],
    light: usize,
    bounce: u8,
    throughput: Vec3,
    radiance: Vec3,
}

/// One reusable, fallibly allocated continuation. The Vec header stays in the
/// 4096-byte host slot; its exact single-element capacity is billed by admit.
/// Keeping an empty slot between samples avoids any per-ray allocation.
struct PendingPixelSlot(Vec<PendingPixel>);

impl PendingPixelSlot {
    fn required_bytes() -> u64 {
        std::mem::size_of::<PendingPixel>() as u64
    }

    fn new(cancel: &CancelToken) -> job::Result<Self> {
        cancel.check()?;
        let mut slot = Vec::new();
        slot.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
        if slot.capacity() != 1 {
            return Err(error(TraceError::MemoryLimit));
        }
        cancel.check()?;
        Ok(Self(slot))
    }

    fn as_ref(&self) -> Option<&PendingPixel> {
        self.0.first()
    }

    fn as_mut(&mut self) -> Option<&mut PendingPixel> {
        self.0.first_mut()
    }

    fn is_none(&self) -> bool {
        self.0.is_empty()
    }

    #[cfg(test)]
    fn is_some(&self) -> bool {
        !self.is_none()
    }

    fn insert(&mut self, value: PendingPixel) -> job::Result<()> {
        if self.0.capacity() != 1 || !self.0.is_empty() {
            return Err(invalid("pending pixel slot is unavailable"));
        }
        // Capacity is already admitted and reserved: this cannot allocate.
        self.0.push(value);
        Ok(())
    }

    fn clear(&mut self) {
        self.0.clear();
    }

    fn release(&mut self) {
        self.0 = Vec::new();
    }
}

#[derive(Clone, Copy)]
struct OpticalPath {
    ray: Ray,
    throughput: Vec3,
    medium: Option<usize>,
    /// Boundary or opaque reflection position, before the numerical spawn offset.
    segment_start: Vec3,
    boundaries: u8,
    /// Opaque reflection depth is independent of the dielectric interface count.
    bounce: u8,
}

struct DielectricPixel {
    path: OpticalPath,
    stack: [Option<OpticalPath>; MAX_BOUNDARIES as usize + 1],
    stack_len: usize,
    paths: u16,
    primary_check: usize,
    selector: usize,
    selected: Option<usize>,
    ready: bool,
}

/// One fallibly reserved optional slot. Branches do not copy PendingPixel, own
/// lighting state, encode pixels, or allocate outside the existing job reservation.
struct OpticalTask {
    certificates: [Option<Certificate>; MAX_OVERRIDES],
    pending: Option<DielectricPixel>,
    preparation: Vec<super::legacy_certificates::Task>,
}

impl DielectricPixel {
    fn new(ray: Ray) -> Self {
        Self {
            path: OpticalPath { ray, throughput: Vec3::new(1.0, 1.0, 1.0), medium: None, segment_start: ray.origin(), boundaries: 0, bounce: 0 },
            stack: [None; MAX_BOUNDARIES as usize + 1],
            stack_len: 0,
            paths: 1,
            primary_check: 0,
            selector: 0,
            selected: None,
            ready: false,
        }
    }

    fn push(&mut self, path: OpticalPath) -> job::Result<()> {
        if !bounded_radiance(path.throughput) {
            return Err(invalid("dielectric branch throughput exceeds finite bound"));
        }
        if path.throughput == Vec3::ZERO {
            return Ok(());
        }
        if self.paths >= MAX_PATHS {
            return Err(error(TraceError::WorkLimit));
        }
        *self.stack.get_mut(self.stack_len).ok_or_else(|| error(TraceError::MemoryLimit))? = Some(path);
        self.stack_len += 1;
        self.paths += 1;
        Ok(())
    }

    fn advance(&mut self) -> job::Result<bool> {
        if self.stack_len == 0 {
            return Ok(false);
        }
        self.stack_len -= 1;
        self.path = self.stack.get_mut(self.stack_len).and_then(Option::take).ok_or_else(|| invalid("optical path stack"))?;
        self.selector = 0;
        self.selected = None;
        self.ready = false;
        Ok(true)
    }
}

/// Reset only per-hit transport state; retain the shared sum across Fresnel leaves.
fn resume_optical_path(pending: &mut PendingPixel, path: OpticalPath) {
    pending.ray = path.ray;
    pending.throughput = path.throughput;
    pending.bounce = path.bounce;
    pending.repeatable_primary = false;
    pending.cursor = TraceCursor::new(path.ray, false);
    pending.hit = None;
    pending.surface_cursor = 0;
    pending.surface_index = None;
    pending.surface_ready = false;
    pending.emission_cursor = 0;
    pending.light = 0;
    pending.visibility = [true; 8];
    pending.punctual_index = 0;
    pending.punctual_shadow = false;
    pending.punctual_ready = false;
    pending.punctual_value = Vec3::ZERO;
    pending.area_light = 0;
    pending.area_index = 0;
    pending.area_shadow = false;
    pending.area_ready = false;
    pending.area_value = Vec3::ZERO;
    pending.environment_sample = 0;
    pending.environment_sum = Vec3::ZERO;
    pending.environment_cursor = None;
    pending.environment_value = Vec3::ZERO;
}

#[path = "image_caustics.rs"]
mod caustics;
#[path = "image_indirect.rs"]
mod indirect_image;

pub struct ImageTask {
    maps: Vec<job::textures::cpu_cache::CpuTextureCache>,
    aging: Vec<super::aging::Task>,
    path: Vec<indirect_image::State>,
    caustics: Vec<caustics::Task>,
    punctual_diagnostics: job::PunctualDiagnostics,
    progressive: Option<Progressive>,
    sampling: Vec<job::adaptive::SamplingReport>,
    denoise: Vec<super::denoise::Guides>,
    optical: Vec<OpticalTask>,
    glass: Vec<super::glass_mesh::Task>,
    anisotropic_targets: [Option<PlanarTarget>; 2],
    environment: Option<crate::lighting::environment_input::EnvironmentState>,
    scene: ProductScene,
    request: ImageRequest,
    options: RaytraceOptions,
    cancel: CancelToken,
    admission: Admission,
    lights: Lighting,
    emissions: Vec<(usize, super::emission::Emission)>,
    effects: Vec<(usize, crate::surface_patterns::PreparedEffect)>,
    work: WorkBudget,
    clip: (f64, f64),
    pupil_sample: Option<[f64; 2]>,
    triangles: Vec<Triangle>,
    looks: Vec<Look>,
    body: usize,
    triangle: usize,
    /// The current body's face looks as (face, index into `faces`), sorted by
    /// face with only the first entry per face, so each triangle is one lookup.
    face_looks: Vec<(u32, usize)>,
    face_looks_ready: bool,
    builder: Option<BvhBuilder>,
    bvh: Option<Bvh>,
    build_used: u64,
    pixels: Vec<u8>,
    linear: Vec<[f32; 4]>,
    output: Vec<job::output::OutputTask>,
    linear_exr: Option<Vec<u8>>,
    pixel: usize,
    sample: u8,
    spatial: u8,
    primary_coverage: u16,
    spatial_radiance: Vec3,
    finish_spatial: bool,
    emit_spatial_pixel: bool,
    pixel_radiance: Vec3,
    pending: PendingPixelSlot,
    encoder: Option<job::encoding::PngEncoding>,
    done: bool,
}
// Same host slot: a future feature build must prove the actual target layout.
const _: [(); 1] = [(); (std::mem::size_of::<ImageTask>() <= 4096) as usize];

/// CPU continuations. Preview bytes are complete PNGs but acquire a transferable
/// host lease and identity only when the owning host publishes them.
pub enum ImagePoll {
    Pending(Progress),
    Preview { png: Vec<u8>, samples_per_pixel: u32 },
    Complete(Vec<u8>),
}

impl ImageTask {
    pub fn sampling_report(&self) -> Option<job::adaptive::SamplingReport> {
        self.sampling.first().cloned()
    }
    pub fn punctual_diagnostics(&self) -> Option<job::PunctualDiagnostics> {
        (!self.punctual_diagnostics.is_empty()).then_some(self.punctual_diagnostics)
    }

    pub fn new(scene: ProductScene, request: ImageRequest, cancel: CancelToken, options: RaytraceOptions) -> job::Result<Self> {
        Self::new_with_environment(scene, request, cancel, options, None)
    }
    pub fn new_with_environment(
        scene: ProductScene,
        request: ImageRequest,
        cancel: CancelToken,
        options: RaytraceOptions,
        input: Option<crate::lighting::environment_input::EnvironmentInput>,
    ) -> job::Result<Self> {
        Self::new_prepared(scene, request, cancel, options, input, None)
    }
    pub(crate) fn new_prepared(
        scene: ProductScene,
        request: ImageRequest,
        cancel: CancelToken,
        options: RaytraceOptions,
        input: Option<crate::lighting::environment_input::EnvironmentInput>,
        proof: Option<CertifiedOptics>,
    ) -> job::Result<Self> {
        cancel.check()?;
        let mut admission = admit_layout(&scene, &request, &options)?;
        if options.dielectrics.is_empty() && proof.is_some() {
            return Err(invalid("unexpected optical proof without selected boundaries"));
        }
        let certified_work = proof.as_ref().map_or(0, CertifiedOptics::work_used);
        let (legacy_proof, mut glass) = if let Some(proof) = proof {
            if options.path.is_some() {
                if proof.legacy.is_some() || proof.general.len() != 1 || !proof.general.first().is_some_and(|task| task.ready()) {
                    return Err(invalid("unexpected or incomplete general optical proof"));
                }
                (None, proof.general)
            } else {
                (Some(proof.into_legacy()?), Vec::new())
            }
        } else {
            (None, Vec::new())
        };
        let mut optical = Vec::new();
        if !options.dielectrics.is_empty() && options.path.is_none() {
            let mut preparation = Vec::new();
            let certificates = if let Some(values) = legacy_proof {
                values
            } else {
                preparation.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
                if preparation.capacity() != 1 {
                    return Err(error(TraceError::MemoryLimit));
                }
                cancel.check()?;
                preparation.push(super::legacy_certificates::Task::new(&scene, &request, &options).map_err(error)?);
                [None; MAX_OVERRIDES]
            };
            optical.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if optical.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            optical.push(OpticalTask { certificates, pending: None, preparation });
        } else if legacy_proof.is_some() {
            return Err(invalid("unexpected legacy optical proof"));
        }
        if options.path.is_some() && !options.dielectrics.is_empty() && glass.is_empty() {
            glass.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if glass.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            glass.push(super::glass_mesh::Task::new(&scene, &options)?);
        }
        if input.is_some() {
            options.validate_environment_reflections(&scene)?;
        }
        let extra = input.as_ref().map_or(Ok(0), |e| e.required_bytes()).map_err(environment_error)?;
        admission.estimated_total_bytes = admission
            .estimated_total_bytes
            .checked_add(extra)
            .filter(|v| *v <= options.budget.limits().max_job_bytes)
            .ok_or_else(|| error(TraceError::MemoryLimit))?;
        admission.preparation_bytes = admission.preparation_bytes.checked_add(extra).ok_or_else(|| error(TraceError::MemoryLimit))?;
        let environment = input.map(|e| e.begin()).transpose().map_err(environment_error)?;
        let lights = lighting(&options)?;
        let mut work = WorkBudget::new(options.budget.limits().max_work_units).map_err(error)?;
        work.charge(certified_work, &cancel).map_err(error)?;
        let anisotropic_targets = anisotropic_faces::prepare(&scene, &options, || work.tick(&cancel).map_err(error))?;
        let mut effects = Vec::new();
        if let Some(values) = &options.surface_effects {
            effects.try_reserve_exact(values.len()).map_err(|_| error(TraceError::AllocationFailed))?;
            if effects.capacity() != values.len() {
                return Err(error(TraceError::MemoryLimit));
            }
            for value in values {
                work.tick(&cancel).map_err(error)?;
                let effect = value.prepare()?;
                let index = scene
                    .meshes
                    .iter()
                    .position(|body| body.name == value.body)
                    .ok_or_else(|| JobError::new(ErrorCode::InvalidRequest, "surface effect body missing"))?;
                // Identity is omitted to preserve the existing pixel path and bytes.
                if !effect.is_identity() {
                    effects.push((index, effect));
                }
            }
        }
        let mut emissions = Vec::new();
        if let Some(values) = &options.emissions {
            emissions.try_reserve_exact(values.len()).map_err(|_| error(TraceError::AllocationFailed))?;
            if emissions.capacity() != values.len() {
                return Err(error(TraceError::MemoryLimit));
            }
            for value in values {
                work.tick(&cancel).map_err(error)?;
                // Skip zero terms to preserve the baseline floating-point path exactly.
                if value.strength != 0.0 && value.color.iter().any(|v| *v != 0.0) {
                    emissions.push((value.body_index, super::emission::Emission::new(value)?));
                }
            }
        }
        let radius =
            if scene.meshes.is_empty() { 10.0 } else { scene.bounds.diagonal().max(10.0) + scene.bounds.center().dist(request.camera.target) };
        if !radius.is_finite() {
            return Err(invalid("invalid product bounds"));
        }
        let clip = request.camera.clip(radius);
        let mut triangles = Vec::new();
        let mut looks = Vec::new();
        let mut pixels = Vec::new();
        triangles.try_reserve_exact(admission.triangles as usize).map_err(|_| error(TraceError::AllocationFailed))?;
        looks.try_reserve_exact(admission.triangles as usize).map_err(|_| error(TraceError::AllocationFailed))?;
        pixels.try_reserve_exact(request.width as usize * request.height as usize * 4).map_err(|_| error(TraceError::AllocationFailed))?;
        // Allocator capacities are checked, not assumed equal to requested capacities.
        let actual = BvhBuilder::required_bytes(admission.triangles as usize, triangles.capacity(), limits(options.budget)).map_err(error)?;
        if actual != BvhBuilder::required_bytes(admission.triangles as usize, admission.triangles as usize, limits(options.budget)).map_err(error)?
            || looks.capacity() != admission.triangles as usize
            || pixels.capacity() != request.width as usize * request.height as usize * 4
        {
            return Err(error(TraceError::MemoryLimit));
        }
        let mut output = Vec::new();
        if options.denoise || options.output.as_deref().is_some_and(|settings| !settings.identity_display() || settings.linear_exr) {
            output.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if output.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
        }
        let mut path = Vec::new();
        if options.path.is_some() {
            cancel.check()?;
            path.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if path.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            path.push(indirect_image::State::default());
        }
        let mut denoise = Vec::new();
        if options.denoise {
            denoise.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if denoise.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            denoise.push(super::denoise::Guides::new(request.width, request.height)?);
        }
        let mut maps = Vec::new();
        if let Some(resources) = &request.textures {
            maps.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if maps.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            maps.push(job::textures::cpu_cache::CpuTextureCache::new(resources.clone(), &cancel)?);
        }
        let mut aging = Vec::new();
        if options.aging.as_deref().is_some_and(job::aging::AgingStack::active) {
            cancel.check()?;
            aging.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if aging.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            aging.push(super::aging::Task::default());
        }
        let pending = PendingPixelSlot::new(&cancel)?;
        let budget = options.budget;
        let mut sampling = Vec::new();
        if options.adaptive.is_some() {
            cancel.check()?;
            sampling.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if sampling.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
        }
        let adaptive = options.adaptive.as_deref();
        let target = options.preview_target()?;
        let progressive = options
            .progressive
            .map(|options| -> job::Result<Progressive> {
                let bytes = CameraFilm::required_bytes(request.width, request.height, options, adaptive, budget)?;
                let film = CameraFilm::new(request.width, request.height, options, adaptive, budget, bytes, &cancel)?;
                Ok(Progressive { film, options, target, resolving: false, resolve_pixel: 0 })
            })
            .transpose()?;
        let mut caustics = Vec::new();
        if let Some(options) = options.caustics {
            caustics.try_reserve_exact(1).map_err(|_| error(TraceError::AllocationFailed))?;
            if caustics.capacity() != 1 {
                return Err(error(TraceError::MemoryLimit));
            }
            caustics.push(caustics::Task::new(options)?);
        }
        Ok(Self {
            maps,
            aging,
            path,
            caustics,
            punctual_diagnostics: Default::default(),
            progressive,
            sampling,
            denoise,
            optical,
            glass,
            anisotropic_targets,
            environment,
            scene,
            request,
            options,
            cancel,
            admission,
            lights,
            emissions,
            effects,
            clip,
            pupil_sample: None,
            work,
            triangles,
            looks,
            body: 0,
            triangle: 0,
            face_looks: Vec::new(),
            face_looks_ready: false,
            builder: None,
            bvh: None,
            build_used: 0,
            pixels,
            linear: Vec::new(),
            output,
            linear_exr: None,
            pixel: 0,
            sample: 0,
            spatial: 0,
            primary_coverage: 0,
            spatial_radiance: Vec3::ZERO,
            finish_spatial: false,
            emit_spatial_pixel: false,
            pixel_radiance: Vec3::ZERO,
            pending,
            encoder: None,
            done: false,
        })
    }
    pub fn progress(&self) -> Progress {
        let (phase, done, total) = if self.optical.first().is_some_and(|optical| !optical.preparation.is_empty()) {
            (Phase::Preparing, 0, 1)
        } else if self.done {
            (Phase::Completed, 1, 1)
        } else if !self.output.is_empty() {
            (Phase::Encoding, 0, u64::from(self.request.width) * u64::from(self.request.height))
        } else if let Some(e) = &self.encoder {
            (Phase::Encoding, e.row() as u64, self.request.height as u64)
        } else if let Some(maps) = self.maps.first().filter(|maps| !maps.ready()) {
            let (done, total) = maps.preparation_rows();
            (Phase::Preparing, done, total)
        } else if self.glass.first().is_some_and(|glass| !glass.ready()) {
            (Phase::Preparing, 0, 1)
        } else if self.bvh.is_some() && self.caustics.first().is_some_and(|map| !map.ready()) {
            let (done, total) = self.caustics.first().map_or((0, 1), caustics::Task::progress);
            (Phase::Preparing, done, total)
        } else if self.bvh.is_some() && self.denoise.first().is_some_and(|guides| !guides.ready()) {
            (
                Phase::Preparing,
                self.denoise.first().map_or(0, |guides| guides.completed_pixels() as u64),
                u64::from(self.request.width) * u64::from(self.request.height),
            )
        } else if let Some(progressive) = &self.progressive {
            let count = u64::from(self.request.width) * u64::from(self.request.height);
            if !progressive.film.ready() {
                (Phase::Preparing, progressive.film.initialized() as u64, count)
            } else if progressive.film.resetting() {
                (Phase::Preparing, progressive.film.reset_progress() as u64, count)
            } else if progressive.resolving {
                (Phase::Encoding, progressive.resolve_pixel as u64, count)
            } else if self.bvh.is_some() {
                let partial = if self.pixel as u64 == count { 0 } else { self.pixel as u64 };
                (Phase::Running, u64::from(progressive.film.samples()) * count + partial, u64::from(progressive.target) * count)
            } else {
                (Phase::Preparing, self.triangles.len() as u64, self.admission.triangles)
            }
        } else if self.bvh.is_some() {
            (Phase::Running, self.pixel as u64, self.request.width as u64 * self.request.height as u64)
        } else {
            (Phase::Preparing, self.triangles.len() as u64, self.admission.triangles)
        };
        Progress { phase, done, total }
    }
    fn prepare_one(&mut self) -> job::Result<()> {
        self.work.tick(&self.cancel).map_err(error)?;
        let Some(body) = self.scene.meshes.get(self.body) else {
            let triangles = std::mem::take(&mut self.triangles);
            let expected = BvhBuilder::required_bytes(triangles.len(), triangles.capacity(), limits(self.options.budget)).map_err(error)?;
            let builder = BvhBuilder::new(triangles, limits(self.options.budget), &self.cancel).map_err(error)?;
            if builder.admitted_bytes() > expected {
                return Err(error(TraceError::MemoryLimit));
            }
            self.builder = Some(builder);
            return Ok(());
        };
        let Some(indices) = body.mesh.triangles.get(self.triangle) else {
            self.body += 1;
            self.triangle = 0;
            self.face_looks_ready = false;
            return Ok(());
        };
        if !self.face_looks_ready {
            // Built once per body instead of scanning `faces` for every triangle.
            // The first entry for a face wins, as the scan this replaces did.
            self.work.charge(body.faces.len() as u64, &self.cancel).map_err(error)?;
            self.face_looks.clear();
            self.face_looks.try_reserve_exact(body.faces.len()).map_err(|_| error(TraceError::AllocationFailed))?;
            self.face_looks.extend(body.faces.iter().enumerate().map(|(index, look)| (look.face, index)));
            self.face_looks.sort_unstable();
            self.face_looks.dedup_by_key(|entry| entry.0);
            self.face_looks_ready = true;
        }
        let mut vertices = [Vec3::ZERO; 3];
        let mut normals = [Vec3::ZERO; 3];
        for ((p, n), i) in vertices.iter_mut().zip(normals.iter_mut()).zip(indices) {
            *p = *body.mesh.positions.get(*i as usize).ok_or_else(|| invalid("triangle vertex index"))?;
            *n = body.mesh.normals.get(*i as usize).copied().unwrap_or(Vec3::ZERO);
        }
        let face = body.mesh.tri_face.get(self.triangle).copied();
        let mut color = body.color;
        let mut surface = body.surface;
        let look = face
            .and_then(|face| self.face_looks.binary_search_by_key(&face, |entry| entry.0).ok())
            .and_then(|at| self.face_looks.get(at))
            .and_then(|entry| body.faces.get(entry.1));
        if let Some(look) = look {
            color = look.color;
            surface = look.surface;
        }
        let surface = match surface {
            Some(s) => s,
            None => OpaqueSurface::new(Vec3::new(srgb8_to_linear(color[0]), srgb8_to_linear(color[1]), srgb8_to_linear(color[2])), 0.0, 0.7, 1.5)
                .map_err(|_| invalid("invalid scalar surface"))?,
        };
        self.triangles.push(Triangle::new(vertices).map_err(error)?);
        self.looks.push(Look { body_index: self.body, face, has_face_override: look.is_some(), surface, normals, vertices });
        self.triangle += 1;
        Ok(())
    }
    /// Move the final native raw companion once. Provisional passes never populate it.
    pub fn take_linear_exr(&mut self) -> Option<Vec<u8>> {
        self.linear_exr.take()
    }
    fn preserves_display(&self) -> bool {
        !self.options.denoise && self.options.output.as_deref().is_none_or(|o| o.identity_display())
    }
    fn needs_linear_pass(&self) -> bool {
        self.options.denoise
            || self
                .options
                .output
                .as_deref()
                .is_some_and(|o| !o.identity_display() || (o.linear_exr && self.progressive.as_ref().is_none_or(|p| p.film.samples() == p.target)))
    }
    fn append_linear(&mut self, radiance: Vec3, covered: u16, samples: u16) -> job::Result<()> {
        if !self.needs_linear_pass() {
            return Ok(());
        }
        if samples == 0 || covered > samples || !bounded_radiance(radiance) || (covered == 0 && radiance != Vec3::ZERO) {
            return Err(invalid("invalid raw CPU radiance or coverage"));
        }
        self.work.tick(&self.cancel).map_err(error)?;
        let count = self.request.width as usize * self.request.height as usize;
        if self.linear.capacity() == 0 {
            self.linear.try_reserve_exact(count).map_err(|_| error(TraceError::AllocationFailed))?;
        }
        if self.linear.capacity() != count || self.linear.len() >= count {
            return Err(error(TraceError::MemoryLimit));
        }
        let pixel = [radiance.x as f32, radiance.y as f32, radiance.z as f32, (f64::from(covered) / f64::from(samples)) as f32];
        if pixel.iter().any(|v| !v.is_finite() || *v < 0.0) || pixel[3] > 1.0 {
            return Err(invalid("raw CPU float conversion exceeds finite bounds"));
        }
        self.cancel.check()?;
        self.linear.push(pixel);
        Ok(())
    }
    fn start_output(&mut self) -> job::Result<()> {
        if self.output.capacity() != 1 || !self.output.is_empty() {
            return Err(invalid("CPU output slot is not admitted or available"));
        }
        let settings = match self.options.output.as_deref() {
            Some(settings) => *settings,
            None if self.options.denoise => Default::default(),
            None => return Err(invalid("missing CPU output settings")),
        };
        let final_pass = self.progressive.as_ref().is_none_or(|p| p.film.samples() == p.target);
        let coverage_samples = match &self.progressive {
            Some(progressive) => u16::try_from(progressive.film.samples()).map_err(|_| invalid("CPU coverage sample count overflow"))?,
            None if self.options.primary_samples == 1 => 1,
            None => u16::from(self.options.primary_samples)
                .checked_mul(u16::from(self.sample_count()))
                .ok_or_else(|| invalid("CPU spatial coverage sample count overflow"))?,
        };
        let presentation = settings.presentation(self.options.exposure_ev, self.request.background, self.request.transparent_background);
        let task = job::output::OutputTask::new(
            self.request.width,
            self.request.height,
            self.admission.encoded_limit,
            std::mem::take(&mut self.linear),
            std::mem::take(&mut self.pixels),
            presentation,
            self.preserves_display(),
            final_pass && settings.linear_exr,
            self.options.denoise,
            coverage_samples,
            self.cancel.clone(),
            &mut |units| self.work.charge(units, &self.cancel).map_err(error),
        )?;
        self.output.push(task);
        Ok(())
    }
    fn complete_png(&mut self, png: Vec<u8>, charged: bool) -> job::Result<ImagePoll> {
        self.cancel.check()?;
        if let Some(progressive) = &mut self.progressive {
            if !charged {
                self.work.charge(png.len() as u64, &self.cancel).map_err(error)?;
            }
            let samples_per_pixel = progressive.film.samples();
            if samples_per_pixel < progressive.target {
                progressive.resolving = false;
                progressive.resolve_pixel = 0;
                self.encoder = None;
                self.pixels.clear();
                self.pixel = 0;
                return Ok(ImagePoll::Preview { png, samples_per_pixel });
            }
        }
        if let Some(report) = self.progressive.as_ref().map(|p| p.film.report()).transpose()?.flatten() {
            if self.sampling.capacity() != 1 || !self.sampling.is_empty() {
                return Err(invalid("CPU adaptive report slot is not admitted or available"));
            }
            self.cancel.check()?;
            self.sampling.push(report);
        }
        self.release_completed_work()?;
        Ok(ImagePoll::Complete(png))
    }
    fn sample_count(&self) -> u8 {
        self.options.reflections.as_ref().filter(|r| !r.bodies.is_empty()).map_or(1, |r| r.samples)
    }
    fn finish_sample(&mut self, radiance: Vec3) -> job::Result<()> {
        if let Some(progressive) = &mut self.progressive {
            if self.primary_coverage > 1 {
                return Err(invalid("progressive camera sample has duplicate primary coverage"));
            }
            let ordinal = progressive.film.samples();
            progressive.film.add(self.pixel, ordinal, [radiance.x, radiance.y, radiance.z], self.primary_coverage == 1, &self.cancel, &mut || {
                self.work.tick(&self.cancel).map_err(error)
            })?;
            self.pending.clear();
            self.primary_coverage = 0;
            self.pixel += 1;
            return Ok(());
        }
        if self.options.primary_samples != 1 {
            return self.finish_spatial_sample(radiance);
        }
        // Only the current fixed-centre, nonselected primary path is identical
        // across reflection samples: directional inputs and the environment's
        // fixed u-grid do not depend on self.sample, and this path never bounces.
        // Secondary nonselected hits and selected null samples still require R.
        let repeats =
            if self.sample == 0 && self.pending.as_ref().is_some_and(|p| p.repeatable_primary && p.bounce == 0) { self.sample_count() } else { 1 };
        // Reuse the shading result, but retain the original addition order,
        // per-add bound and final divisor exactly. At most64 scalar additions,
        // no repeated BVH/BSDF/environment work or new allocation/work budget.
        for _ in 0..repeats {
            self.pixel_radiance += radiance;
            if !self.pixel_radiance.is_finite()
                || [self.pixel_radiance.x, self.pixel_radiance.y, self.pixel_radiance.z].into_iter().any(|v| !(0.0..=1e12).contains(&v))
            {
                return Err(invalid("reflection radiance exceeds finite transport bound"));
            }
            self.sample += 1;
        }
        self.pending.clear();
        if self.sample == self.sample_count() {
            let radiance = self.pixel_radiance / self.sample as f64;
            self.append_linear(radiance, 1, 1)?;
            if self.preserves_display() {
                let display = map_to_display(radiance, self.options.exposure_ev).map_err(error)?;
                self.pixels.extend_from_slice(&[encode8(display.x), encode8(display.y), encode8(display.z), 255]);
            }
            self.pixel += 1;
            self.sample = 0;
            self.pixel_radiance = Vec3::ZERO;
        }
        Ok(())
    }
    fn finish_spatial_sample(&mut self, radiance: Vec3) -> job::Result<()> {
        // Same per-R-add finite bound and denominator, including zero/null events.
        self.pixel_radiance += radiance;
        if !bounded_radiance(self.pixel_radiance) {
            return Err(invalid("reflection radiance exceeds finite transport bound"));
        }
        self.sample = self.sample.checked_add(1).ok_or_else(|| invalid("reflection sample overflow"))?;
        if self.sample > self.sample_count() {
            return Err(invalid("reflection sample count exceeded"));
        }
        self.finish_spatial = self.sample == self.sample_count();
        let retain = !self.finish_spatial && self.pending.as_ref().is_some_and(|p| p.repeatable_primary && p.bounce == 0 && p.hit.is_some());
        if retain {
            // A completed primary, never a traversal/shading intermediate. The
            // existing light cursor has no other len+1 state (at most 8 lights).
            let completed = self.lights.lights().len() + 1;
            self.pending.as_mut().ok_or_else(|| invalid("missing reusable primary"))?.light = completed;
        } else {
            self.pending.clear();
        }
        Ok(())
    }
    fn spatial_transition(&mut self) -> job::Result<bool> {
        if self.finish_spatial {
            self.work.tick(&self.cancel).map_err(error)?;
            self.spatial_radiance += self.pixel_radiance / f64::from(self.sample_count()) / f64::from(self.options.primary_samples);
            if !bounded_radiance(self.spatial_radiance) {
                return Err(invalid("spatial radiance exceeds finite transport bound"));
            }
            self.pixel_radiance = Vec3::ZERO;
            self.sample = 0;
            self.spatial = self.spatial.checked_add(1).ok_or_else(|| invalid("spatial sample overflow"))?;
            self.finish_spatial = false;
            self.emit_spatial_pixel = self.spatial == self.options.primary_samples;
            return Ok(true);
        }
        if self.emit_spatial_pixel {
            self.work.tick(&self.cancel).map_err(error)?;
            let attempts = u16::from(self.options.primary_samples)
                .checked_mul(u16::from(self.sample_count()))
                .filter(|n| *n <= 1024)
                .ok_or_else(|| invalid("spatial coverage bound"))?;
            self.append_linear(self.spatial_radiance, self.primary_coverage, attempts)?;
            if self.preserves_display() {
                let rgba = composite_spatial_alpha(
                    self.spatial_radiance,
                    self.primary_coverage,
                    attempts,
                    self.request.background,
                    self.options.exposure_ev,
                    self.request.transparent_background,
                )?;
                self.cancel.check()?;
                self.pixels.extend_from_slice(&rgba);
            }
            self.pixel += 1;
            self.spatial = 0;
            self.primary_coverage = 0;
            self.spatial_radiance = Vec3::ZERO;
            self.emit_spatial_pixel = false;
            return Ok(true);
        }
        Ok(false)
    }
    fn pixel_one(&mut self) -> job::Result<()> {
        if self.options.primary_samples != 1 && self.pending.as_ref().is_some_and(|p| p.light > self.lights.lights().len()) {
            let pending = self.pending.as_ref().ok_or_else(|| invalid("missing reusable primary"))?;
            if pending.light != self.lights.lights().len() + 1
                || !pending.repeatable_primary
                || pending.bounce != 0
                || pending.hit.is_none()
                || self.sample == 0
                || self.sample >= self.sample_count()
                || self.spatial >= self.options.primary_samples
                || self.finish_spatial
                || self.emit_spatial_pixel
            {
                return Err(invalid("invalid reusable primary state"));
            }
            if !pending.surface_ready
                || pending.surface_cursor != self.effects.len()
                || pending.emission_cursor != self.emissions.len()
                || pending.punctual_index != self.options.punctual_lights.as_ref().map_or(0, Vec::len)
                || pending.area_light != self.options.area_lights.as_ref().map_or(0, Vec::len)
                || pending.punctual_shadow
                || pending.punctual_ready
                || pending.area_shadow
                || pending.area_ready
                || pending.environment_cursor.is_some()
                || pending.environment_sample != self.environment.as_ref().map_or(0, |e| e.samples)
            {
                return Err(invalid("incomplete reusable primary shading"));
            }
            let radiance = pending.radiance;
            // One actual scalar continuation per logical R; no bulk R loop or
            // fabricated traversal debit. Check cancel/limit before mutations.
            self.work.tick(&self.cancel).map_err(error)?;
            let bvh = self.bvh.as_ref().ok_or_else(|| invalid("missing reusable primary BVH"))?;
            let shared = resolved_surface_hit(
                &PreparedScene { bvh, primitives: &self.looks, source: &self.scene },
                pending,
                &self.effects,
                self.maps.first(),
                self.aging.first(),
            )?;
            if self.optical.first().is_some_and(|o| o.pending.is_some())
                || self.options.dielectrics.iter().any(|input| input.body_index == shared.body_index)
            {
                return Err(invalid("optical primary cannot reuse shading"));
            }
            if self.options.reflections.as_ref().is_some_and(|r| r.bodies.iter().any(|entry| entry.body == shared.body_name)) {
                return Err(invalid("selected primary cannot reuse shading"));
            }
            self.primary_coverage =
                self.primary_coverage.checked_add(1).filter(|n| *n <= 1024).ok_or_else(|| invalid("spatial coverage overflow"))?;
            return self.finish_spatial_sample(radiance);
        }
        if self.options.primary_samples != 1 && self.spatial_transition()? {
            return Ok(());
        }
        let bvh = self.bvh.as_ref().ok_or_else(|| invalid("missing image BVH"))?;
        if self.pending.is_none() {
            if self.options.lens.is_some_and(|lens| lens.aperture_radius_mm > 0.0) && self.pupil_sample.is_none() {
                self.work.tick(&self.cancel).map_err(error)?;
                let progressive = self.progressive.as_ref().ok_or_else(|| invalid("physical pupil requires progressive camera sampling"))?;
                self.pupil_sample = Some(progressive.variates(self.pixel, 0x4c454e53)?);
                return Ok(());
            }
            self.work.tick(&self.cancel).map_err(error)?;
            let width = self.request.width as usize;
            // This proof belongs to the generator for a fixed (pixel, spatial),
            // not the camera/request globally. Future per-R jitter must revoke it.
            let (ray, repeatable_primary) = if let Some(progressive) = &self.progressive {
                let [dx, dy] = progressive.variates(self.pixel, 0)?;
                let x = (self.pixel % width) as f64 + dx;
                let y = (self.pixel / width) as f64 + dy;
                let ray = if let Some(lens) = self.options.lens.filter(|lens| lens.aperture_radius_mm > 0.0) {
                    let pupil = self.pupil_sample.take().ok_or_else(|| invalid("missing physical pupil sample"))?;
                    lens_primary_ray(&self.request, x, y, self.clip, lens, pupil).map_err(error)?
                } else {
                    primary_ray(&self.request, x, y, self.clip).map_err(error)?
                };
                (ray, false)
            } else if self.options.primary_samples == 1 {
                // Preserve the exact legacy centre path, including its reuse proof.
                (primary_ray(&self.request, (self.pixel % width) as f64 + 0.5, (self.pixel / width) as f64 + 0.5, self.clip).map_err(error)?, true)
            } else {
                let [dx, dy] = primary_offset(self.options.primary_samples, self.spatial)?;
                (primary_ray(&self.request, (self.pixel % width) as f64 + dx, (self.pixel / width) as f64 + dy, self.clip).map_err(error)?, true)
            };
            if let Some(optical) = self.optical.first_mut() {
                if optical.pending.is_some() {
                    return Err(invalid("previous optical sample was not drained"));
                }
                optical.pending = Some(DielectricPixel::new(ray));
            }
            self.pending.insert(PendingPixel {
                surface_cursor: 0,
                surface_index: None,
                surface_ready: false,
                emission_cursor: 0,
                punctual_index: 0,
                punctual_shadow: false,
                punctual_ready: false,
                punctual_value: Vec3::ZERO,
                area_light: 0,
                area_index: 0,
                area_shadow: false,
                area_ready: false,
                area_value: Vec3::ZERO,

                repeatable_primary,
                environment_sample: 0,
                environment_sum: Vec3::ZERO,
                environment_cursor: None,
                environment_value: Vec3::ZERO,
                ray,
                cursor: TraceCursor::new(ray, false),
                hit: None,
                visibility: [true; 8],
                light: 0,
                bounce: 0,
                throughput: Vec3::new(1.0, 1.0, 1.0),
                radiance: Vec3::ZERO,
            })?;
            return Ok(());
        }
        if let Some(optical) = self.optical.first_mut() {
            let state = optical.pending.as_mut().ok_or_else(|| invalid("missing optical primary state"))?;
            if state.primary_check < self.options.dielectrics.len() {
                self.work.tick(&self.cancel).map_err(error)?;
                if let Some(Certificate::ClosedBox(bounds)) = optical.certificates.get(state.primary_check).copied().flatten()
                    && (dielectric::contains(bounds, state.path.ray.origin()) || dielectric::contains(bounds, self.request.camera.eye()))
                {
                    return Err(invalid("camera or near plane inside a dielectric volume is unsupported"));
                }
                state.primary_check += 1;
                return Ok(());
            }
            if state.primary_check != self.options.dielectrics.len() {
                return Err(invalid("invalid primary certificate cursor"));
            }
        }
        let scene = PreparedScene { bvh, primitives: &self.looks, source: &self.scene };
        let pending = self.pending.as_mut().ok_or_else(|| invalid("missing pixel state"))?;
        let primary_segment =
            pending.bounce == 0 && self.optical.first().and_then(|o| o.pending.as_ref()).is_none_or(|state| state.path.boundaries == 0);
        if pending.hit.is_none() {
            let Some(hit) = pending.cursor.step(bvh, &mut self.work, &self.cancel).map_err(error)? else {
                return Ok(());
            };
            let Some(hit) = hit else {
                if self.optical.first().and_then(|o| o.pending.as_ref()).is_some_and(|state| state.path.medium.is_some()) {
                    return Err(invalid("dielectric path escaped without its certified exit"));
                }
                if primary_segment {
                    if let Some(optical) = self.optical.first_mut() {
                        optical.pending = None;
                    }
                    if self.options.primary_samples != 1 || self.progressive.is_some() {
                        // A miss is one of S*R attempts, never the completed pixel.
                        return self.finish_sample(Vec3::ZERO);
                    }
                    self.append_linear(Vec3::ZERO, 0, 1)?;
                    if self.preserves_display() {
                        let rgba = if self.request.transparent_background {
                            [0; 4]
                        } else {
                            let [r, g, b] = self.request.background;
                            [r, g, b, 255]
                        };
                        self.pixels.extend_from_slice(&rgba);
                    }
                    self.pixel += 1;
                    self.sample = 0;
                    self.pixel_radiance = Vec3::ZERO;
                    self.pending.clear();
                    return Ok(());
                }
                if let Some(environment) = &self.environment {
                    let emitted =
                        environment.view().map_err(environment_error)?.radiance_linear_srgb(pending.ray.direction()).map_err(environment_error)?;
                    pending.radiance += multiply(pending.throughput, emitted);
                }
                if self.environment.is_none()
                    && let Some(environment) = self.options.environment
                {
                    let [r, g, b] = environment.color;
                    pending.radiance += multiply(pending.throughput, Vec3::new(r, g, b) * environment.intensity);
                }
                let radiance = pending.radiance;
                if !bounded_radiance(radiance) {
                    return Err(invalid("secondary environment radiance exceeds finite bound"));
                }
                return self.finish_transport_path(radiance);
            };
            if primary_segment && (self.options.primary_samples != 1 || self.progressive.is_some()) {
                self.primary_coverage =
                    self.primary_coverage.checked_add(1).filter(|n| *n <= 1024).ok_or_else(|| invalid("spatial coverage overflow"))?;
            }
            pending.hit = Some(hit);
            if let Some(maps) = self.maps.first_mut() {
                maps.reset_hit();
            }
            if let Some(aging) = self.aging.first_mut() {
                aging.reset();
            }
            pending.light = 0;
            let shared = scene.resolve_hit(pending.ray, hit).map_err(error)?;
            let mode =
                self.options.reflections.as_ref().and_then(|r| r.bodies.iter().find(|entry| entry.body == shared.body_name).map(|entry| entry.mode));
            pending.repeatable_primary &= primary_segment && mode.is_none();
            if let Some(optical) = self.optical.first_mut() {
                let state = optical.pending.as_mut().ok_or_else(|| invalid("missing optical hit state"))?;
                state.selector = 0;
                state.selected = None;
                state.ready = false;
                // Traversal consumed this continuation; selector work begins next call.
                return Ok(());
            }
            pending.surface_ready = self.effects.is_empty() && self.maps.is_empty() && self.aging.is_empty();
            if !pending.surface_ready {
                // Traversal already consumed this continuation's unit. Scan one
                // effect per following call, before beginning any lighting stage.
                return Ok(());
            }
            if self.options.shadows && !self.lights.lights().is_empty() && mode != Some(job::ReflectionMode::Mirror) {
                let light = self.lights.lights().first().ok_or_else(|| invalid("missing first light"))?;
                pending.cursor = TraceCursor::new(shared.spawn(light.direction()).map_err(error)?, true);
                return Ok(());
            }
            pending.light = self.lights.lights().len();
            return Ok(());
        } else if self.optical.first().and_then(|o| o.pending.as_ref()).is_some_and(|state| !state.ready) {
            return self.dielectric_hit_one();
        } else if !pending.surface_ready {
            self.work.tick(&self.cancel).map_err(error)?;
            if let Some((body_index, _)) = self.effects.get(pending.surface_cursor) {
                let hit = pending.hit.ok_or_else(|| invalid("missing surface effect hit"))?;
                let look = self.looks.get(hit.primitive_index).ok_or_else(|| invalid("missing surface effect appearance"))?;
                let index = pending.surface_cursor;
                pending.surface_cursor += 1;
                if *body_index == look.body_index {
                    pending.surface_index = Some(index);
                    pending.surface_cursor = self.effects.len();
                }
                return Ok(());
            }
            if pending.surface_cursor != self.effects.len() {
                return Err(invalid("invalid surface effect scan state"));
            }
            if let Some(maps) = self.maps.first_mut() {
                if !maps.hit_started() {
                    let shared = unmapped_surface_hit(&scene, pending, &self.effects)?;
                    let has_face_override = self.looks.get(shared.primitive_index).is_none_or(|look| look.has_face_override);
                    let footprint = primary_footprint(
                        &self.request,
                        &self.options,
                        self.progressive.as_ref(),
                        self.pixel,
                        self.spatial,
                        self.clip,
                        shared.position,
                        shared.oriented_geometric_normal(),
                    )?;
                    maps.begin_hit(
                        crate::surface_patterns::ShadingSurface { surface: shared.surface, shading_normal: shared.shading_normal },
                        (!has_face_override).then_some(shared.body_index),
                        job::textures::cpu_preparation::MapPoint {
                            position: shared.position,
                            geometric_normal: shared.oriented_geometric_normal(),
                            view_direction: -pending.ray.direction(),
                        },
                        footprint,
                    )?;
                }
                if !maps.hit_ready() {
                    let ready = maps.advance_hit()?;
                    if !ready || !self.aging.is_empty() {
                        return Ok(());
                    }
                }
            }
            if let Some(aging) = self.aging.first_mut() {
                if !aging.started() {
                    let shared = unaged_surface_hit(&scene, pending, &self.effects, self.maps.first())?;
                    aging.begin(
                        crate::surface_patterns::ShadingSurface { surface: shared.surface, shading_normal: shared.shading_normal },
                        shared.position,
                        shared.geometric_normal,
                        shared.body_index,
                        super::aging::eligible(&self.options, shared.body_index, shared.body_name),
                    )?;
                }
                if !aging.ready() {
                    let stack = self.options.aging.as_deref().ok_or_else(|| invalid("CPU aging stack disappeared"))?;
                    if !aging.advance(stack)? {
                        return Ok(());
                    }
                }
            }
            pending.surface_ready = true;
            let shared = resolved_surface_hit(&scene, pending, &self.effects, self.maps.first(), self.aging.first())?;
            let mode =
                self.options.reflections.as_ref().and_then(|r| r.bodies.iter().find(|entry| entry.body == shared.body_name).map(|entry| entry.mode));
            if self.options.shadows && !self.lights.lights().is_empty() && mode != Some(job::ReflectionMode::Mirror) {
                let light = self.lights.lights().first().ok_or_else(|| invalid("missing first surface light"))?;
                pending.cursor = TraceCursor::new(shared.spawn(light.direction()).map_err(error)?, true);
            } else {
                pending.light = self.lights.lights().len();
            }
            return Ok(());
        } else if pending.light < self.lights.lights().len() {
            let Some(shadow) = pending.cursor.step(bvh, &mut self.work, &self.cancel).map_err(error)? else {
                return Ok(());
            };
            *pending.visibility.get_mut(pending.light).ok_or_else(|| invalid("light visibility index"))? = shadow.is_none();
            pending.light += 1;
            if let Some(light) = self.lights.lights().get(pending.light) {
                let shared = resolved_surface_hit(&scene, pending, &self.effects, self.maps.first(), self.aging.first())?;
                pending.cursor = TraceCursor::new(shared.spawn(light.direction()).map_err(error)?, true);
                return Ok(());
            }
            return Ok(());
        }
        if let Some((body_index, emission)) = self.emissions.get(pending.emission_cursor) {
            self.work.tick(&self.cancel).map_err(error)?;
            let hit = pending.hit.ok_or_else(|| invalid("missing emission hit"))?;
            let look = self.looks.get(hit.primitive_index).ok_or_else(|| invalid("missing emission appearance"))?;
            pending.emission_cursor += 1;
            if *body_index == look.body_index {
                let emitted = emission.radiance(hit.geometry.geometric_normal.dot(-pending.ray.direction()) > 0.0);
                pending.radiance += multiply(pending.throughput, emitted);
                if !bounded_radiance(pending.radiance) {
                    return Err(invalid("emission path radiance exceeds finite bound"));
                }
                pending.emission_cursor = self.emissions.len();
            }
            return Ok(());
        }
        if pending.punctual_index < self.options.punctual_lights.as_ref().map_or(0, Vec::len) {
            let shared = resolved_surface_hit(&scene, pending, &self.effects, self.maps.first(), self.aging.first())?;
            let mode =
                self.options.reflections.as_ref().and_then(|r| r.bodies.iter().find(|entry| entry.body == shared.body_name).map(|entry| entry.mode));
            let face = self.looks.get(shared.primitive_index).ok_or_else(|| invalid("punctual face missing"))?.face;
            let target = anisotropic_faces::target_index(&self.options, shared.body_index, face)
                .map(|i| self.anisotropic_targets.get(i).copied().flatten().ok_or_else(|| invalid("punctual anisotropic target missing")))
                .transpose()?;
            punctual_one(pending, &self.options, bvh, (shared, target, mode), &mut self.work, &self.cancel, &mut self.punctual_diagnostics)?;
            return Ok(());
        }
        if pending.area_light < self.options.area_lights.as_ref().map_or(0, Vec::len) {
            let shared = resolved_surface_hit(&scene, pending, &self.effects, self.maps.first(), self.aging.first())?;
            let mode =
                self.options.reflections.as_ref().and_then(|r| r.bodies.iter().find(|entry| entry.body == shared.body_name).map(|entry| entry.mode));
            let face = self.looks.get(shared.primitive_index).ok_or_else(|| invalid("area face missing"))?.face;
            let target = anisotropic_faces::target_index(&self.options, shared.body_index, face)
                .map(|i| self.anisotropic_targets.get(i).copied().flatten().ok_or_else(|| invalid("area anisotropic target missing")))
                .transpose()?;
            let ordinal = self.progressive.as_ref().map(|p| p.identity(self.pixel).map(|i| i.ordinal)).transpose()?.unwrap_or(0);
            let key = area_sample_key(self.pixel as u64, self.spatial, self.options.primary_samples, ordinal)?;
            let key = self.progressive.as_ref().map_or(Ok(key), |p| p.area_key(self.pixel, key))?;
            area_one(pending, &self.options, bvh, (shared, target, mode), &mut self.work, &self.cancel, key)?;
            return Ok(());
        }
        if let Some(cursor) = &mut pending.environment_cursor {
            let Some(blocker) = cursor.step(bvh, &mut self.work, &self.cancel).map_err(error)? else {
                return Ok(());
            };
            if blocker.is_none() {
                pending.environment_sum += pending.environment_value;
            }
            pending.environment_cursor = None;
            pending.environment_sample += 1;
            return Ok(());
        }
        if pending.light == self.lights.lights().len() {
            self.work.tick(&self.cancel).map_err(error)?;
            let shared = resolved_surface_hit(&scene, pending, &self.effects, self.maps.first(), self.aging.first())?;
            let mode =
                self.options.reflections.as_ref().and_then(|r| r.bodies.iter().find(|entry| entry.body == shared.body_name).map(|entry| entry.mode));
            let view = -pending.ray.direction();
            let geometric = shared.oriented_geometric_normal();
            // Disjoint estimators: selected reflectors use BSDF transport to the environment;
            // only nonselected opaque hits use environment next-event estimates.
            if mode.is_none()
                && let Some(environment) = &self.environment
            {
                if pending.environment_sample < environment.samples {
                    let side = match environment.samples {
                        1 => 1,
                        4 => 2,
                        16 => 4,
                        _ => 8,
                    };
                    let i = pending.environment_sample;
                    let u = if let Some(progressive) = &self.progressive {
                        let [dx, dy] = progressive.variates(self.pixel, 0x1000 + u64::from(pending.bounce) * 128 + u64::from(i))?;
                        [(f64::from(i / side) + dx) / f64::from(side), (f64::from(i % side) + dy) / f64::from(side)]
                    } else if side == 1 {
                        [0.25, 0.375]
                    } else {
                        [(f64::from(i / side) + 0.5) / f64::from(side), (f64::from(i % side) + 0.5) / f64::from(side)]
                    };
                    let sample = environment
                        .view()
                        .map_err(environment_error)?
                        .direct_sample_linear_srgb(u, shared.surface, shared.shading_normal, geometric, view)
                        .map_err(environment_error)?;
                    pending.environment_value = sample.contribution_linear_srgb;
                    if self.options.shadows && sample.contribution_linear_srgb.len2() > 0.0 {
                        pending.environment_cursor = Some(TraceCursor::new(shared.spawn(sample.direction).map_err(error)?, true));
                    } else {
                        pending.environment_sum += pending.environment_value;
                        pending.environment_sample += 1;
                    }
                    return Ok(());
                }
                pending.radiance += multiply(pending.throughput, pending.environment_sum / f64::from(environment.samples));
            }
            let face = self.looks.get(shared.primitive_index).ok_or_else(|| invalid("missing captured face"))?.face;
            let target_index = anisotropic_faces::target_index(&self.options, shared.body_index, face);
            if mode != Some(job::ReflectionMode::Mirror) {
                let visible = |index: usize, light: Vec3| {
                    Ok(geometric.dot(light) > 0.0 && *pending.visibility.get(index).ok_or(TraceError::Internal("light visibility"))?)
                };
                let direct = if let Some(index) = target_index {
                    self.anisotropic_targets
                        .get(index)
                        .copied()
                        .flatten()
                        .ok_or_else(|| invalid("missing certified anisotropic face"))?
                        .shade(&self.lights, shared.surface, geometric, view, visible)
                        .map_err(error)?
                } else {
                    self.lights.shade_linear(shared.surface, shared.shading_normal, view, visible).map_err(error)?
                };
                pending.radiance += multiply(pending.throughput, direct);
            }
            let max_bounces = self.options.reflections.as_ref().map_or(0, |r| r.max_bounces);
            if let Some(mode) = mode.filter(|_| pending.bounce < max_bounces) {
                let samples = self.options.reflections.as_ref().map_or(1, |r| u64::from(r.samples));
                let u = if let Some(progressive) = &self.progressive {
                    progressive.variates(self.pixel, 0x100 + u64::from(pending.bounce))?
                } else if self.options.primary_samples == 1 {
                    reflection::variates(self.pixel as u64, self.sample as u64, pending.bounce as u64, samples).map_err(error)?
                } else {
                    let key = spatial_key(self.pixel as u64, self.spatial, self.options.primary_samples)?;
                    reflection::variates(key, self.sample as u64, pending.bounce as u64, samples).map_err(error)?
                };
                let sampled = match (mode, target_index) {
                    (job::ReflectionMode::Mirror, _) => reflection::mirror(shared.surface, shared.shading_normal, view),
                    (job::ReflectionMode::RoughSpecular, Some(index)) => self
                        .anisotropic_targets
                        .get(index)
                        .copied()
                        .flatten()
                        .ok_or_else(|| invalid("missing anisotropic reflection target"))?
                        .sample(shared.surface, geometric, view, u),
                    (job::ReflectionMode::RoughSpecular, None) => reflection::rough_specular(shared.surface, shared.shading_normal, view, u),
                }
                .map_err(error)?;
                if let Some(sample) = sampled.filter(|s| s.direction.dot(geometric) > 0.0) {
                    pending.throughput = multiply(pending.throughput, sample.weight);
                    if !pending.throughput.is_finite() {
                        return Err(invalid("nonfinite reflection throughput"));
                    }
                    if pending.throughput.len2() > 0.0 {
                        pending.ray = shared.spawn(sample.direction).map_err(error)?;
                        pending.cursor = TraceCursor::new(pending.ray, false);
                        pending.hit = None;
                        pending.surface_cursor = 0;
                        pending.surface_index = None;
                        pending.surface_ready = false;
                        pending.emission_cursor = 0;
                        pending.light = 0;
                        pending.visibility = [true; 8];
                        pending.punctual_index = 0;
                        pending.punctual_shadow = false;
                        pending.punctual_ready = false;
                        pending.punctual_value = Vec3::ZERO;
                        pending.area_light = 0;
                        pending.area_index = 0;
                        pending.area_shadow = false;
                        pending.area_ready = false;
                        pending.area_value = Vec3::ZERO;

                        pending.environment_sample = 0;
                        pending.environment_sum = Vec3::ZERO;
                        pending.environment_cursor = None;
                        pending.environment_value = Vec3::ZERO;
                        pending.bounce += 1;
                        if let Some(optical) = self.optical.first_mut() {
                            let state = optical.pending.as_mut().ok_or_else(|| invalid("missing reflected optical path"))?;
                            state.path.ray = pending.ray;
                            state.path.throughput = pending.throughput;
                            state.path.segment_start = shared.position;
                            state.path.bounce = pending.bounce;
                            state.selector = 0;
                            state.selected = None;
                            state.ready = false;
                        }
                        return Ok(());
                    }
                }
            }
            let radiance = pending.radiance;
            return self.finish_transport_path(radiance);
        }
        Ok(())
    }
    /// Complete a transport branch. Only a drained optical stack completes one R sample.
    fn finish_transport_path(&mut self, radiance: Vec3) -> job::Result<()> {
        if let Some(optical) = self.optical.first_mut() {
            let state = optical.pending.as_mut().ok_or_else(|| invalid("missing optical sample"))?;
            if state.advance()? {
                let pending = self.pending.as_mut().ok_or_else(|| invalid("missing optical continuation"))?;
                resume_optical_path(pending, state.path);
                return Ok(());
            }
            optical.pending = None;
        }
        self.finish_sample(radiance)
    }

    /// Each selector and each interface is a separate charged continuation. Traversal has
    /// already yielded with the captured hit, and opaque hits rejoin the shared light stages.
    fn dielectric_hit_one(&mut self) -> job::Result<()> {
        self.work.tick(&self.cancel).map_err(error)?;
        let optical = self.optical.first_mut().ok_or_else(|| invalid("missing optical task"))?;
        let state = optical.pending.as_mut().ok_or_else(|| invalid("missing optical sample"))?;
        let pending = self.pending.as_mut().ok_or_else(|| invalid("missing optical hit"))?;
        if state.ready {
            return Err(invalid("optical hit already consumed"));
        }
        let hit = pending.hit.ok_or_else(|| invalid("missing captured optical hit"))?;
        let look = self.looks.get(hit.primitive_index).ok_or_else(|| invalid("missing optical appearance"))?;
        if let Some(input) = self.options.dielectrics.get(state.selector) {
            let index = state.selector;
            state.selector += 1;
            if input.body_index == look.body_index {
                state.selected = Some(index);
                state.selector = self.options.dielectrics.len();
            }
            return Ok(());
        }
        if state.selector != self.options.dielectrics.len() {
            return Err(invalid("invalid optical selector state"));
        }
        let bvh = self.bvh.as_ref().ok_or_else(|| invalid("missing optical BVH"))?;
        let scene = PreparedScene { bvh, primitives: &self.looks, source: &self.scene };
        // Optics always uses the certified geometric boundary, before optional opaque
        // shading-normal effects. Distance starts before the numerical spawn offset.
        let shared = scene.resolve_hit(pending.ray, hit).map_err(error)?;
        if let Some(index) = state.path.medium {
            let medium = self.options.dielectrics.get(index).ok_or_else(|| invalid("active dielectric medium"))?;
            let distance = shared.position.dist(state.path.segment_start);
            pending.throughput = multiply(pending.throughput, dielectric::attenuation(medium.absorption_per_mm, distance).map_err(error)?);
            if !bounded_radiance(pending.throughput) {
                return Err(invalid("dielectric throughput exceeds finite bound"));
            }
        }
        state.ready = true;
        let Some(index) = state.selected else {
            pending.surface_ready = self.effects.is_empty() && self.maps.is_empty() && self.aging.is_empty();
            if !pending.surface_ready {
                return Ok(());
            }
            let mode =
                self.options.reflections.as_ref().and_then(|r| r.bodies.iter().find(|entry| entry.body == shared.body_name).map(|entry| entry.mode));
            if self.options.shadows && !self.lights.lights().is_empty() && mode != Some(job::ReflectionMode::Mirror) {
                let light = self.lights.lights().first().ok_or_else(|| invalid("missing optical opaque light"))?;
                pending.cursor = TraceCursor::new(shared.spawn(light.direction()).map_err(error)?, true);
            } else {
                pending.light = self.lights.lights().len();
            }
            return Ok(());
        };
        let medium = self.options.dielectrics.get(index).ok_or_else(|| invalid("selected dielectric medium"))?;
        if medium.body_index != shared.body_index || medium.body_name != shared.body_name {
            return Err(invalid("optical captured identity changed"));
        }
        pending.repeatable_primary = false;
        state.path.ray = pending.ray;
        state.path.throughput = pending.throughput;
        state.path.bounce = pending.bounce;
        if state.path.boundaries == MAX_BOUNDARIES {
            // Explicit finite-depth preview: unresolved continuation is black, while
            // already accumulated terms and the other bounded branches remain intact.
            let radiance = pending.radiance;
            return self.finish_transport_path(radiance);
        }
        if state.path.boundaries > MAX_BOUNDARIES {
            return Err(invalid("invalid dielectric boundary depth"));
        }
        let next_depth = state.path.boundaries + 1;
        let normal = shared.oriented_geometric_normal();
        let direction = state.path.ray.direction();
        let certificate = optical.certificates.get(index).copied().flatten().ok_or_else(|| invalid("missing dielectric certificate"))?;
        let (optics, reflected_weight, transmitted_weight, next_medium) = match certificate {
            Certificate::ThinSheet => {
                if state.path.medium.is_some() {
                    return Err(invalid("thin sheet inside dielectric medium"));
                }
                let (optics, reflected, transmitted) = dielectric::thin_sheet(direction, normal, medium).map_err(error)?;
                (optics, reflected, transmitted, None)
            }
            Certificate::ClosedBox(bounds) => {
                let boundary_axes = (0..3)
                    .filter(|axis| {
                        let p = super::component(shared.position, *axis);
                        p == super::component(bounds.min(), *axis) || p == super::component(bounds.max(), *axis)
                    })
                    .count();
                if boundary_axes > 1 {
                    return Err(invalid("dielectric box edge or corner has an ambiguous interface normal"));
                }
                let (incident, transmitted, next_medium) = if shared.front_face {
                    if state.path.medium.is_some() {
                        return Err(invalid("nested dielectric entry"));
                    }
                    (1.0, medium.ior, Some(index))
                } else {
                    if state.path.medium != Some(index) {
                        return Err(invalid("dielectric exit without matching entry"));
                    }
                    (medium.ior, 1.0, None)
                };
                let optics = dielectric::interface(direction, normal, incident, transmitted).map_err(error)?;
                let f = optics.reflectance;
                let t = (1.0 - f) * (incident / transmitted).powi(2);
                (optics, Vec3::new(f, f, f), Vec3::new(t, t, t), next_medium)
            }
        };
        state.push(OpticalPath {
            ray: shared.spawn(optics.reflected).map_err(error)?,
            throughput: dielectric::multiply(state.path.throughput, reflected_weight),
            medium: state.path.medium,
            segment_start: shared.position,
            boundaries: next_depth,
            bounce: pending.bounce,
        })?;
        if let Some(direction) = optics.transmitted {
            state.push(OpticalPath {
                ray: shared.spawn(direction).map_err(error)?,
                throughput: dielectric::multiply(state.path.throughput, transmitted_weight),
                medium: next_medium,
                segment_start: shared.position,
                boundaries: next_depth,
                bounce: pending.bounce,
            })?;
        }
        let radiance = pending.radiance;
        self.finish_transport_path(radiance)
    }

    /// Legacy final-only callers keep their exact contract. Progressive callers
    /// must consume `step_with_previews`, so no checkpoint is silently discarded.
    pub fn step(&mut self, units: usize) -> job::Result<TaskPoll> {
        self.cancel.check()?;
        if self.progressive.is_some() {
            return Err(JobError::new(ErrorCode::InvalidRequest, "CPU progressive tasks require step_with_previews"));
        }
        match self.step_with_previews(units)? {
            ImagePoll::Pending(progress) => Ok(TaskPoll::Pending(progress)),
            ImagePoll::Complete(png) => Ok(TaskPoll::Complete(png)),
            ImagePoll::Preview { .. } => Err(invalid("fixed image produced a progressive checkpoint")),
        }
    }

    fn release_completed_work(&mut self) -> job::Result<()> {
        self.done = true;
        self.progressive = None;
        self.anisotropic_targets = [None, None];
        self.options.anisotropic_faces = [None, None];
        self.environment = None;
        self.scene.meshes = Vec::new();
        self.looks = Vec::new();
        self.bvh = None;
        self.builder = None;
        self.triangles = Vec::new();
        self.pixels = Vec::new();
        self.linear = Vec::new();
        self.output = Vec::new();
        self.denoise = Vec::new();
        self.options.output = None;
        self.options.adaptive = None;
        self.options.volume = None;
        self.pending.release();
        self.path = Vec::new();
        self.caustics = Vec::new();
        self.request.raytrace = None;
        self.options.lights = None;
        self.options.emissions = None;
        self.emissions = Vec::new();
        self.options.surface_effects = None;
        self.maps = Vec::new();
        self.request.textures = None;
        self.options.aging = None;
        self.aging = Vec::new();
        self.options.dielectrics = Vec::new();
        self.options.environment = None;
        self.options.sun = None;
        self.options.sky = None;
        self.optical = Vec::new();
        self.glass = Vec::new();
        self.effects = Vec::new();
        self.options.punctual_lights = None;
        self.options.area_lights = None;
        self.options.reflections = None;
        self.lights = Lighting::new(Vec::new()).map_err(error)?;
        self.encoder = None;
        Ok(())
    }

    fn resolve_progressive_one(&mut self) -> job::Result<()> {
        self.work.tick(&self.cancel).map_err(error)?;
        let progressive = self.progressive.as_ref().ok_or_else(|| invalid("missing progressive resolve state"))?;
        let count = self.request.width as usize * self.request.height as usize;
        if progressive.resolve_pixel < count {
            let (rgb, covered, samples) = progressive.film.pixel(progressive.resolve_pixel)?;
            let radiance = Vec3::new(rgb[0], rgb[1], rgb[2]);
            self.append_linear(radiance, covered, samples)?;
            if self.preserves_display() {
                let rgba = composite_spatial_alpha(
                    radiance,
                    covered,
                    samples,
                    self.request.background,
                    self.options.exposure_ev,
                    self.request.transparent_background,
                )?;
                self.cancel.check()?;
                self.pixels.extend_from_slice(&rgba);
            }
            self.progressive.as_mut().ok_or_else(|| invalid("missing progressive resolve state"))?.resolve_pixel += 1;
        } else if self.needs_linear_pass() {
            self.start_output()?;
        } else {
            let capacity = usize::try_from(self.admission.encoded_limit).map_err(|_| error(TraceError::MemoryLimit))?;
            let mut output = Vec::new();
            output.try_reserve_exact(capacity).map_err(|_| error(TraceError::AllocationFailed))?;
            if output.capacity() != capacity {
                return Err(error(TraceError::MemoryLimit));
            }
            self.cancel.check()?;
            self.encoder = Some(job::encoding::PngEncoding::with_output(
                self.request.width,
                self.request.height,
                self.admission.encoded_limit,
                self.cancel.clone(),
                output,
            )?);
        }
        Ok(())
    }

    /// At most four continuations/encoding rows. One cumulative work budget spans
    /// geometry preparation, every absolute camera sample and every checkpoint.
    pub fn step_with_previews(&mut self, units: usize) -> job::Result<ImagePoll> {
        self.cancel.check()?;
        if units == 0 || units > 16384 || self.done {
            return Err(JobError::new(ErrorCode::InvalidRequest, "invalid raytrace step or completed task"));
        }
        for _ in 0..units.min(4) {
            if self.optical.first().is_some_and(|optical| !optical.preparation.is_empty()) {
                let optical = self.optical.first_mut().ok_or_else(|| invalid("missing optical preparation"))?;
                let task = optical.preparation.first_mut().ok_or_else(|| invalid("missing legacy certificate cursor"))?;
                if task.ready() {
                    self.work.tick(&self.cancel).map_err(error)?;
                    let proof = optical
                        .preparation
                        .pop()
                        .ok_or_else(|| invalid("missing completed legacy certificate"))?
                        .into_proof(self.work.used())
                        .map_err(error)?;
                    optical.certificates = proof.into_legacy()?;
                    optical.preparation = Vec::new();
                } else {
                    task.step(&self.scene, &self.options, &mut self.work, &self.cancel).map_err(legacy_error)?;
                }
            } else if self.progressive.as_ref().is_some_and(|p| !p.film.ready()) {
                self.progressive
                    .as_mut()
                    .ok_or_else(|| invalid("missing progressive initialization"))?
                    .film
                    .initialize_one(&self.cancel, &mut || self.work.tick(&self.cancel).map_err(error))?;
            } else if !self.output.is_empty() {
                let guides = self.denoise.first().map(super::denoise::Guides::pixels).transpose()?;
                let counts = self.progressive.as_ref().map(|p| p.film.counts()).transpose()?.flatten();
                let output = self.output.first_mut().ok_or_else(|| invalid("missing CPU output task"))?;
                match output.step(guides, counts, &mut |units| self.work.charge(units, &self.cancel).map_err(error))? {
                    TaskPoll::Pending(_) => {}
                    TaskPoll::Complete(png) => {
                        let output = self.output.pop().ok_or_else(|| invalid("missing completed CPU output task"))?;
                        let (rgba, exr) = output.finish()?;
                        self.pixels = rgba;
                        self.linear_exr = exr;
                        return self.complete_png(png, true);
                    }
                }
            } else if let Some(encoder) = &mut self.encoder {
                if self.progressive.is_some() {
                    self.work
                        .charge(if encoder.row() < self.request.height as usize { u64::from(self.request.width) } else { 1 }, &self.cancel)
                        .map_err(error)?;
                }
                if let Some(png) = encoder.step(&self.pixels)? {
                    return self.complete_png(png, false);
                }
            } else if self.progressive.as_ref().is_some_and(|p| p.resolving) {
                self.resolve_progressive_one()?;
            } else if self.maps.first().is_some_and(|maps| !maps.ready()) {
                self.maps
                    .first_mut()
                    .ok_or_else(|| invalid("CPU map cache disappeared"))?
                    .prepare_one(&self.cancel, &mut |units| self.work.charge(units, &self.cancel).map_err(error))?;
            } else if self.pixel == 0 && self.progressive.as_ref().is_some_and(|p| p.film.pilot_complete()) {
                // The last pilot first takes the ordinary complete-pass resolve,
                // finishing and PNG handoff. Only complete_png resets pixel to0;
                // keep that pilot's film/counts available to finishing and host
                // preview metadata until the next cooperative step begins reset.
                self.progressive
                    .as_mut()
                    .ok_or_else(|| invalid("missing CPU pilot handoff"))?
                    .film
                    .begin_production(&self.cancel, &mut || self.work.tick(&self.cancel).map_err(error))?;
            } else if self.progressive.as_ref().is_some_and(|p| p.film.resetting()) {
                self.progressive
                    .as_mut()
                    .ok_or_else(|| invalid("missing CPU production reset"))?
                    .film
                    .reset_one(&self.cancel, &mut || self.work.tick(&self.cancel).map_err(error))?;
            } else if self.glass.first().is_some_and(|glass| !glass.ready()) {
                self.glass.first_mut().ok_or_else(|| invalid("CPU glass certificate disappeared"))?.step(
                    &self.scene,
                    &self.options,
                    &mut self.work,
                    &self.cancel,
                )?;
            } else if self.environment.as_ref().is_some_and(|e| !e.ready()) {
                self.work.tick(&self.cancel).map_err(error)?;
                self.environment
                    .as_mut()
                    .ok_or_else(|| invalid("missing environment preparation"))?
                    .prepare_one(|| self.cancel.is_cancelled())
                    .map_err(environment_error)?;
            } else if self.bvh.is_some() && self.caustics.first().is_some_and(|map| !map.ready()) {
                caustics::step(self)?;
            } else if self.bvh.is_some() && self.denoise.first().is_some_and(|guides| !guides.ready()) {
                let bvh = self.bvh.as_ref().ok_or_else(|| invalid("missing CPU guide BVH"))?;
                self.denoise.first_mut().ok_or_else(|| invalid("missing CPU guide task"))?.step(
                    PreparedScene { bvh, primitives: &self.looks, source: &self.scene },
                    &self.request,
                    &self.options,
                    self.clip,
                    &self.effects,
                    self.maps.first_mut(),
                    self.aging.first_mut(),
                    &mut self.work,
                    &self.cancel,
                )?;
            } else if self.bvh.is_some() {
                if self.pixel == self.request.width as usize * self.request.height as usize {
                    if let Some(progressive) = &mut self.progressive {
                        self.work.tick(&self.cancel).map_err(error)?;
                        // Resolve every complete pass. The host keeps at most two
                        // immutable snapshots without changing sample order.
                        progressive.resolving = true;
                    } else if self.needs_linear_pass() {
                        self.start_output()?;
                    } else {
                        self.encoder = Some(job::encoding::PngEncoding::new(
                            self.request.width,
                            self.request.height,
                            self.admission.encoded_limit,
                            self.cancel.clone(),
                        )?);
                    }
                } else if self.progressive.as_ref().map(|p| p.film.identity(self.pixel, p.options.seed)).transpose()?.is_some_and(|i| i.is_none()) {
                    self.progressive.as_mut().ok_or_else(|| invalid("missing CPU stopped-pixel film"))?.film.skip(
                        self.pixel,
                        &self.cancel,
                        &mut || self.work.tick(&self.cancel).map_err(error),
                    )?;
                    self.pixel += 1;
                } else {
                    if self.options.path.is_some() {
                        indirect_image::step(self)?;
                    } else {
                        self.pixel_one()?;
                    }
                }
            } else if let Some(builder) = &mut self.builder {
                let progress = builder.step(1, &self.cancel).map_err(error)?;
                for _ in self.build_used..progress.work_used {
                    self.work.tick(&self.cancel).map_err(error)?;
                }
                self.build_used = progress.work_used;
                if progress.complete {
                    self.bvh = Some(self.builder.take().ok_or_else(|| invalid("missing builder"))?.finish().map_err(error)?);
                }
            } else {
                self.prepare_one()?;
            }
        }
        Ok(ImagePoll::Pending(self.progress()))
    }
}
/// Apply the already selected deterministic effect to the shared opaque hit.
/// The captured geometric normal, ray origin, visibility and topology are unchanged.
fn resolved_surface_hit<'a>(
    scene: &PreparedScene<'a>,
    pending: &PendingPixel,
    effects: &[(usize, crate::surface_patterns::PreparedEffect)],
    maps: Option<&job::textures::cpu_cache::CpuTextureCache>,
    aging: Option<&super::aging::Task>,
) -> job::Result<SharedHit<'a>> {
    if !pending.surface_ready {
        return Err(invalid("surface effect is not completely resolved"));
    }
    let mut shared = unaged_surface_hit(scene, pending, effects, maps)?;
    if let Some(aging) = aging {
        let changed = aging.surface()?;
        shared.surface = changed.surface;
        shared.shading_normal = changed.shading_normal;
    }
    Ok(shared)
}
fn unaged_surface_hit<'a>(
    scene: &PreparedScene<'a>,
    pending: &PendingPixel,
    effects: &[(usize, crate::surface_patterns::PreparedEffect)],
    maps: Option<&job::textures::cpu_cache::CpuTextureCache>,
) -> job::Result<SharedHit<'a>> {
    let mut shared = unmapped_surface_hit(scene, pending, effects)?;
    if let Some(maps) = maps {
        let mapped = maps.surface()?;
        shared.surface = mapped.surface;
        shared.shading_normal = mapped.shading_normal;
    }
    Ok(shared)
}
fn unmapped_surface_hit<'a>(
    scene: &PreparedScene<'a>,
    pending: &PendingPixel,
    effects: &[(usize, crate::surface_patterns::PreparedEffect)],
) -> job::Result<SharedHit<'a>> {
    if pending.surface_cursor != effects.len() {
        return Err(invalid("surface effect scan is incomplete"));
    }
    let mut shared = scene.resolve_hit(pending.ray, pending.hit.ok_or_else(|| invalid("missing prepared surface hit"))?).map_err(error)?;
    if let Some(index) = pending.surface_index {
        let (body_index, effect) = effects.get(index).ok_or_else(|| invalid("missing selected surface effect"))?;
        if *body_index != shared.body_index {
            return Err(invalid("selected surface effect belongs to another body"));
        }
        let changed = effect.apply(shared.surface, shared.shading_normal, shared.oriented_geometric_normal(), shared.position)?;
        shared.surface = changed.surface;
        shared.shading_normal = changed.shading_normal;
    }
    Ok(shared)
}

/// Adjacent shading-grid rays meet the same captured geometric plane. This is a
/// texture footprint only: no topology or visibility decision uses the plane.
/// A grazing footprint that crosses the horizon selects the coarsest mip.
fn primary_footprint(
    request: &ImageRequest,
    options: &RaytraceOptions,
    progressive: Option<&Progressive>,
    pixel: usize,
    spatial: u8,
    clip: (f64, f64),
    position: Vec3,
    normal: Vec3,
) -> job::Result<Option<[Vec3; 2]>> {
    let width = request.width as usize;
    let offset =
        if let Some(progressive) = progressive { progressive.variates(pixel, 0)? } else { primary_offset(options.primary_samples, spatial)? };
    let x = (pixel % width) as f64 + offset[0];
    let y = (pixel / width) as f64 + offset[1];
    let spacing = if progressive.is_some() { 1.0 } else { 1.0 / f64::from(options.primary_samples).sqrt() };
    if let Some(lens) = options.lens.filter(|lens| lens.aperture_radius_mm > 0.0) {
        // Counter-based lookup reproduces the primary ray's pupil without advancing
        // its sampler or adding a dimension. Hold that pupil for both neighbours.
        let progressive = progressive.ok_or_else(|| invalid("physical pupil requires progressive camera sampling"))?;
        let pupil = progressive.variates(pixel, 0x4c454e53)?;
        plane_footprint(position, normal, spacing, |dx, dy| lens_primary_ray(request, x + dx, y + dy, clip, lens, pupil).map_err(error))
    } else {
        camera_footprint(request, x, y, spacing, clip, position, normal)
    }
}

/// Same geometric-plane footprint for deterministic guide rays, without changing
/// their center sample or the progressive camera's sampling stream.
#[allow(clippy::too_many_arguments)]
pub(super) fn camera_footprint(
    request: &ImageRequest,
    x: f64,
    y: f64,
    spacing: f64,
    clip: (f64, f64),
    position: Vec3,
    normal: Vec3,
) -> job::Result<Option<[Vec3; 2]>> {
    plane_footprint(position, normal, spacing, |dx, dy| primary_ray(request, x + dx, y + dy, clip).map_err(error))
}

fn plane_footprint(
    position: Vec3,
    normal: Vec3,
    spacing: f64,
    mut neighbour: impl FnMut(f64, f64) -> job::Result<Ray>,
) -> job::Result<Option<[Vec3; 2]>> {
    let mut result = [Vec3::ZERO; 2];
    for (output, [dx, dy]) in result.iter_mut().zip([[spacing, 0.0], [0.0, spacing]]) {
        let ray = neighbour(dx, dy)?;
        let denominator = ray.direction().dot(normal);
        if !denominator.is_finite() || denominator.abs() < 1e-12 {
            return Ok(None);
        }
        let distance = (position - ray.origin()).dot(normal) / denominator;
        if !distance.is_finite() || distance < 0.0 {
            return Ok(None);
        }
        *output = ray.origin() + ray.direction() * distance - position;
        if !output.is_finite() {
            return Ok(None);
        }
    }
    Ok(Some(result))
}

fn bounded_radiance(v: Vec3) -> bool {
    v.is_finite() && [v.x, v.y, v.z].into_iter().all(|c| (0.0..=1e12).contains(&c))
}
fn primary_offset(samples: u8, ordinal: u8) -> job::Result<[f64; 2]> {
    let side = match samples {
        1 => 1,
        4 => 2,
        16 => 4,
        _ => return Err(invalid("invalid spatial sample count")),
    };
    if ordinal >= samples {
        return Err(invalid("invalid spatial sample ordinal"));
    }
    Ok([(f64::from(ordinal % side) + 0.5) / f64::from(side), (f64::from(ordinal / side) + 0.5) / f64::from(side)])
}
fn spatial_key(pixel: u64, ordinal: u8, samples: u8) -> job::Result<u64> {
    primary_offset(samples, ordinal)?;
    pixel
        .checked_mul(u64::from(samples))
        .and_then(|n| n.checked_add(u64::from(ordinal)))
        .map(|n| n ^ 0x4141_5052_494d_4152)
        .ok_or_else(|| invalid("spatial seed overflow"))
}
/// Distinguish film and spatial ordinals before sampling an emitter. The legacy
/// single-primary first pass keeps its original key and reference image bytes.
fn area_sample_key(pixel: u64, spatial: u8, spatial_samples: u8, film_sample: u32) -> job::Result<u64> {
    primary_offset(spatial_samples, spatial)?;
    if film_sample >= job::MAX_CPU_SAMPLES_PER_PIXEL {
        return Err(invalid("area-light film sample ordinal exceeds the admitted cap"));
    }
    if spatial_samples == 1 && film_sample == 0 {
        return Ok(pixel);
    }
    pixel
        .checked_mul(u64::from(job::MAX_CPU_SAMPLES_PER_PIXEL) * 16)
        .and_then(|key| key.checked_add(u64::from(film_sample) * 16 + u64::from(spatial)))
        .map(|key| key ^ 0x4152_4541_5341_4d50)
        .ok_or_else(|| invalid("area-light sample identity overflow"))
}

/// Straight-alpha display from primary geometric coverage. Keep the original
/// opaque f64 route untouched, including its unexposed display backplate.
fn composite_spatial_alpha(
    premultiplied: Vec3,
    covered: u16,
    attempts: u16,
    background: [u8; 3],
    exposure: f64,
    transparent: bool,
) -> job::Result<[u8; 4]> {
    if !transparent {
        return composite_spatial(premultiplied, covered, attempts, background, exposure);
    }
    if attempts == 0 || u32::from(attempts) > job::MAX_CPU_SAMPLES_PER_PIXEL || covered > attempts || !bounded_radiance(premultiplied) {
        return Err(invalid("invalid transparent coverage/radiance"));
    }
    if covered == 0 {
        if premultiplied != Vec3::ZERO {
            return Err(invalid("uncovered transparent radiance"));
        }
        return Ok([0; 4]);
    }
    let coverage = f64::from(covered) / f64::from(attempts);
    let alpha = (coverage * 255.0).round() as u8;
    if alpha == 0 {
        return Ok([0; 4]);
    }
    let display = map_to_display(premultiplied / coverage, exposure).map_err(error)?;
    Ok([encode8(display.x), encode8(display.y), encode8(display.z), alpha])
}

fn composite_spatial(premultiplied: Vec3, covered: u16, attempts: u16, background: [u8; 3], exposure: f64) -> job::Result<[u8; 4]> {
    if attempts == 0 || u32::from(attempts) > job::MAX_CPU_SAMPLES_PER_PIXEL || covered > attempts || !bounded_radiance(premultiplied) {
        return Err(invalid("invalid spatial coverage/radiance"));
    }
    if covered == 0 {
        if premultiplied != Vec3::ZERO {
            return Err(invalid("uncovered spatial radiance"));
        }
        return Ok([background[0], background[1], background[2], 255]);
    }
    let coverage = f64::from(covered) / f64::from(attempts);
    let geometry = map_to_display(premultiplied / coverage, exposure).map_err(error)?;
    let display = if covered == attempts {
        geometry
    } else {
        let bg = Vec3::new(srgb8_to_linear(background[0]), srgb8_to_linear(background[1]), srgb8_to_linear(background[2]));
        geometry * coverage + bg * (1.0 - coverage)
    };
    Ok([encode8(display.x), encode8(display.y), encode8(display.z), 255])
}

/// One sample preparation, one traversal operation OR one visible-sum operation.
/// Reuses the existing primary/directional cursor: no second task or heap state.
fn punctual_one(
    pending: &mut PendingPixel,
    options: &RaytraceOptions,
    bvh: &Bvh,
    context: (super::prepared::SharedHit<'_>, Option<PlanarTarget>, Option<job::ReflectionMode>),
    work: &mut WorkBudget,
    cancel: &CancelToken,
    diagnostics: &mut job::PunctualDiagnostics,
) -> job::Result<()> {
    let (shared, target, mode) = context;
    if pending.punctual_shadow {
        if let Some(blocker) = pending.cursor.step(bvh, work, cancel).map_err(error)? {
            if blocker.is_some() {
                pending.punctual_value = Vec3::ZERO;
            }
            pending.punctual_shadow = false;
            pending.punctual_ready = true;
        }
        return Ok(());
    }
    work.tick(cancel).map_err(error)?;
    if pending.punctual_ready {
        add_punctual_radiance(pending, pending.punctual_value, diagnostics);
        pending.punctual_index += 1;
        pending.punctual_ready = false;
        return Ok(());
    }
    let inputs = options.punctual_lights.as_ref().ok_or_else(|| invalid("punctual options missing"))?;
    if mode == Some(job::ReflectionMode::Mirror) {
        pending.punctual_index = inputs.len();
        return Ok(());
    }
    let light = inputs.get(pending.punctual_index).copied().ok_or_else(|| invalid("punctual source index"))?.light().map_err(error)?;
    let sample = light.sample(shared.position).map_err(error)?;
    if let Some(reason) = sample.omitted {
        match reason {
            super::punctual::OmittedSample::NearSource => diagnostics.near_source = diagnostics.near_source.saturating_add(1),
            super::punctual::OmittedSample::RadianceLimit => diagnostics.radiance_limit = diagnostics.radiance_limit.saturating_add(1),
        }
        pending.punctual_index += 1;
        return Ok(());
    }
    let geometric = shared.oriented_geometric_normal();
    let cosine = if target.is_some() { geometric } else { shared.shading_normal }.dot(sample.direction).max(0.0);
    let contribution = if geometric.dot(sample.direction) <= 0.0 || cosine == 0.0 || sample.incident_linear_srgb == Vec3::ZERO {
        Vec3::ZERO
    } else {
        let view = -pending.ray.direction();
        let f = if let Some(target) = target {
            target.direct_brdf(shared.surface, geometric, view, sample.direction).map_err(error)?
        } else {
            shared.surface.brdf(shared.shading_normal, view, sample.direction).map_err(|_| invalid("punctual opaque response"))?
        };
        multiply(f, sample.incident_linear_srgb) * cosine
    };
    if super::lighting::validate_radiance(contribution).is_err() {
        diagnostics.radiance_limit = diagnostics.radiance_limit.saturating_add(1);
        pending.punctual_index += 1;
        return Ok(());
    }
    pending.punctual_value = contribution;
    if options.shadows && contribution != Vec3::ZERO {
        let Some(ray) = sample.shadow_ray(shared).map_err(error)? else {
            diagnostics.shadow_offset_crossed = diagnostics.shadow_offset_crossed.saturating_add(1);
            pending.punctual_index += 1;
            return Ok(());
        };
        pending.cursor = TraceCursor::new(ray, true);
        pending.punctual_shadow = true;
    } else {
        add_punctual_radiance(pending, contribution, diagnostics);
        pending.punctual_index += 1;
    }
    Ok(())
}

fn add_punctual_radiance(pending: &mut PendingPixel, contribution: Vec3, diagnostics: &mut job::PunctualDiagnostics) {
    let candidate = pending.radiance + multiply(pending.throughput, contribution);
    if super::lighting::validate_radiance(candidate).is_ok() {
        pending.radiance = candidate;
    } else {
        diagnostics.radiance_limit = diagnostics.radiance_limit.saturating_add(1);
    }
}

fn multiply(a: Vec3, b: Vec3) -> Vec3 {
    Vec3::new(a.x * b.x, a.y * b.y, a.z * b.z)
}
#[cfg(test)]
fn shadow_ray(ray: Ray, hit: super::Hit, light: Vec3, vertices: [Vec3; 3]) -> super::Result<Ray> {
    let mut n = hit.geometry.geometric_normal;
    if n.dot(light) < 0.0 {
        n = -n;
    }
    let [a, b, c] = hit.geometry.barycentric;
    let [va, vb, vc] = vertices;
    // Reconstruct from captured vertices, not a distant camera. Component-wise
    // rounding bounds avoid an unrelated large X translation displacing a Z plane.
    let p = va * a + vb * b + vc * c;
    let magnitude = |x: f64, y: f64, z: f64| x.abs() * a.abs() + y.abs() * b.abs() + z.abs() * c.abs();
    let e = Vec3::new(magnitude(va.x, vb.x, vc.x), magnitude(va.y, vb.y, vc.y), magnitude(va.z, vb.z, vc.z)) * (8.0 * f64::EPSILON);
    let distance = n.x.abs() * e.x + n.y.abs() * e.y + n.z.abs() * e.z;
    let shifted = p + n * distance;
    let outward = |v: f64, n: f64| {
        if n > 0.0 {
            v.next_up()
        } else if n < 0.0 {
            v.next_down()
        } else {
            v
        }
    };
    let _ = ray; // hit position comes from geometry, independent of camera distance.
    Ray::new(Vec3::new(outward(shifted.x, n.x), outward(shifted.y, n.y), outward(shifted.z, n.z)), light, 0.0_f64.next_up(), super::MAX_DISTANCE_MM)
}

/// A circular pupil in the eye plane, focused at an axial distance. The
/// original primary generator remains untouched for absent or zero aperture.
fn lens_primary_ray(request: &ImageRequest, x: f64, y: f64, clip: (f64, f64), lens: job::ThinLens, pupil: [f64; 2]) -> super::Result<Ray> {
    if lens.aperture_radius_mm == 0.0 {
        return primary_ray(request, x, y, clip);
    }
    if pupil.into_iter().any(|v| !v.is_finite() || !(0.0..1.0).contains(&v)) {
        return Err(TraceError::InvalidInput("thin-lens pupil sample"));
    }
    let camera = &request.camera;
    let (right, up, back) = camera.basis();
    let eye = camera.eye();
    let (_, pinhole) = camera.ray(x, y, request.width as f64, request.height as f64);
    let cosine = pinhole.dot(-back);
    if !cosine.is_finite() || cosine <= 0.0 {
        return Err(TraceError::InvalidInput("thin-lens camera direction"));
    }
    let radius = lens.aperture_radius_mm * pupil[0].sqrt();
    let phi = std::f64::consts::TAU * pupil[1];
    let displacement = (right * phi.cos() + up * phi.sin()) * radius;
    // Work in eye-relative coordinates so large world translations cannot erase
    // a small pupil before computing its aimed direction.
    let focused = pinhole * (lens.focus_distance_mm / cosine);
    let direction = super::unit(focused - displacement).ok_or(TraceError::InvalidInput("thin-lens focus direction"))?;
    let cosine = direction.dot(-back);
    if !cosine.is_finite() || cosine <= 0.0 {
        return Err(TraceError::InvalidInput("thin-lens forward interval"));
    }
    let origin = eye + displacement;
    let depth = (origin - eye).dot(-back);
    let start = (clip.0 - depth) / cosine;
    Ray::new(origin + direction * start, direction, 0.0, (clip.1 - clip.0) / cosine)
}

pub(super) fn primary_ray(request: &ImageRequest, x: f64, y: f64, clip: (f64, f64)) -> super::Result<Ray> {
    let camera = &request.camera;
    let (mut origin, direction) = camera.ray(x, y, request.width as f64, request.height as f64);
    if camera.fov == 0.0 {
        origin -= camera.back() * (camera.distance * 3.0);
    }
    let forward = -camera.back();
    let cosine = direction.dot(forward);
    if !cosine.is_finite() || cosine <= 0.0 {
        return Err(TraceError::InvalidInput("camera ray direction"));
    }
    let depth = (origin - camera.eye()).dot(forward);
    let start = (clip.0 - depth) / cosine;
    let length = (clip.1 - clip.0) / cosine;
    Ray::new(origin + direction * start, direction, 0.0, length)
}

#[cfg(test)]
#[path = "image_tests.rs"]
mod tests;

#[cfg(test)]
#[path = "deterministic_primary_tests.rs"]
mod deterministic_primary_tests;

#[cfg(test)]
#[path = "reflection_image_tests.rs"]
mod reflection_tests;

fn environment_error(e: crate::lighting::HdrError) -> JobError {
    use crate::lighting::HdrErrorCode;
    let code = match e.code {
        HdrErrorCode::Cancelled => ErrorCode::Cancelled,
        HdrErrorCode::LimitExceeded => ErrorCode::LimitExceeded,
        HdrErrorCode::AllocationFailed => ErrorCode::AllocationFailed,
        _ => ErrorCode::InvalidRequest,
    };
    JobError::new(code, e.to_string())
}

#[cfg(test)]
#[path = "primary_aa_tests.rs"]
mod primary_aa_tests;

// One bounded continuation operation, using the same cursor, work accumulator and task.
fn area_one(
    pending: &mut PendingPixel,
    options: &RaytraceOptions,
    bvh: &Bvh,
    context: (super::prepared::SharedHit<'_>, Option<PlanarTarget>, Option<job::ReflectionMode>),
    work: &mut WorkBudget,
    cancel: &CancelToken,
    pixel: u64,
) -> job::Result<()> {
    let (shared, target, mode) = context;
    if pending.area_shadow {
        if let Some(blocker) = pending.cursor.step(bvh, work, cancel).map_err(error)? {
            if blocker.is_some() {
                pending.area_value = Vec3::ZERO;
            }
            pending.area_shadow = false;
            pending.area_ready = true;
        }
        return Ok(());
    }
    work.tick(cancel).map_err(error)?;
    if pending.area_ready {
        pending.radiance += multiply(pending.throughput, pending.area_value);
        super::lighting::validate_radiance(pending.radiance).map_err(error)?;
        pending.area_index += 1;
        pending.area_ready = false;
        return Ok(());
    }
    let inputs = options.area_lights.as_ref().ok_or_else(|| invalid("area options missing"))?;
    if mode == Some(job::ReflectionMode::Mirror) {
        pending.area_light = inputs.len();
        return Ok(());
    }
    let count = options.area_samples.unwrap_or(16);
    if pending.area_index == count {
        pending.area_light += 1;
        pending.area_index = 0;
        return Ok(());
    }
    let input = inputs.get(pending.area_light).ok_or_else(|| invalid("area source index"))?;
    let vec = |[x, y, z]: [f64; 3]| Vec3::new(x, y, z);
    let light = super::area::RectangleLight::new(vec(input.center_mm), vec(input.edge_u_mm), vec(input.edge_v_mm), vec(input.color), input.intensity)
        .map_err(error)?;
    let Some(sample) =
        light.sample(shared.position, pixel, pending.area_light as u32, pending.area_index, count, options.seed.unwrap_or(0)).map_err(error)?
    else {
        pending.area_index += 1;
        return Ok(());
    };
    let geometric = shared.oriented_geometric_normal();
    let cosine = if target.is_some() { geometric } else { shared.shading_normal }.dot(sample.direction()).max(0.0);
    let contribution = if geometric.dot(sample.direction()) <= 0.0 || cosine == 0.0 {
        Vec3::ZERO
    } else {
        let view = -pending.ray.direction();
        let f = if let Some(target) = target {
            target.direct_brdf(shared.surface, geometric, view, sample.direction()).map_err(error)?
        } else {
            shared.surface.brdf(shared.shading_normal, view, sample.direction()).map_err(|_| invalid("area opaque response"))?
        };
        multiply(f, sample.incident()) * cosine
    };
    super::lighting::validate_radiance(contribution).map_err(error)?;
    pending.area_value = contribution;
    if options.shadows && contribution != Vec3::ZERO {
        let origin = shared.spawn(sample.direction()).map_err(error)?.origin();
        pending.cursor = TraceCursor::new(sample.shadow_ray(origin).map_err(error)?, true);
        pending.area_shadow = true;
    } else {
        pending.radiance += multiply(pending.throughput, contribution);
        super::lighting::validate_radiance(pending.radiance).map_err(error)?;
        pending.area_index += 1;
    }
    Ok(())
}

#[cfg(test)]
#[path = "punctual_image_tests.rs"]
mod punctual_image_tests;