solvecraft/docs/render-cpu-celestial.md

# CPU finite Sun and gradient Sky

This source change adds the shared finite Sun and gradient Sky intent to CPU ray
tracing with explicit Indirect lighting (`options.path`). It is an opt-in transport
extension; selecting a light never enables GI or replaces another environment.
Raster remains schematic. The implementation and its renderer, saved/runtime and
pointer-UI tests are included in published `00edaf6a`/tree `38a7f0af` and executed
by CI7. Full CI7 remains red, and dedicated native Sun/Sky or Glass image-quality
acceptance remains pending; see [qualification](render-parity.md#qualification).

`CpuJob.sun` uses the existing Sun direction, angular radius in radians
(0.001…π/2), and relative linear-sRGB radiance (0…100,000,000 per channel).
It is distinct from a hard directional source: a hard source retains
`angular_radius_rad: None`, and the zero-radius/default route keeps its existing
producer/RNG/work behavior. The optional Sun shares the eight-directional limit;
point/spot and rectangle limits are unchanged.

`CpuJob.sky` uses the existing portable `SkyEnvironment::Sky` fields: linear
zenith/horizon/ground RGB, world-Z axis, rotation within ±1,000,000 radians and
intensity 0…100. Its radiance is the same unchanged f32 gradient at the GPU's 256
row centres. Longitude rotation is retained but this axisymmetric gradient is
invariant under it. CPU evaluates a selected row directly; it does not generate
an HDR image, quantize to RGBE or allocate an environment plane. CPU uses uniform
solid-angle proposals; GPU uses its existing alias-table proposals. This is the
same radiance target, not a claim of equal convergence or CPU/GPU pixel identity.

Constant, Sky and HDR illumination are exclusive sources. Finite Sun is additive
with any one of them. HDR retains its existing declared-primary policy, intensity
limit 64 and direct sample count; Sky takes one NEE proposal per shaded bounce.
The built-in HDR library requires explicit replacement consent and refuses an
analytic Sun when the selected HDR already owns its solar disk. Generic HDR bytes
have no inferred solar ownership. Display backplates remain separate from light.

CPU Path samples the finite Sun uniformly over its cap. Environment and Sun NEE
and escaped BSDF contributions each use their own power weight against the same
material PDF, with the actual competitor count and depth endpoint. Delta Glass
escape receives full emitter weight after the existing physical Beer segments.
Nearest geometry/area-emitter endpoints, thin-shadow continuation and certified
nested origins retain their existing contracts. Infinite NEE connections through
closed Glass are still outside the existing supported connection domain, as in
the GPU consumer; this does not add caustic or closed-interface NEE support.

Effects → Maps → Aging still supplies the shared BRDF/PDF and guide material.
Sky/Sun add no guide or snapshot plane. Optional Sun/Sky boxes are billed at actual
`size_of` in the retained request and both owned producer option copies. The
unchanged 4096-byte task slot must contain the enlarged inline option headers;
the static size assertion is retained. The retained Record's optional Sun/Sky
headers and inline Volume header are summed once by the shared fixed metadata
helper on every captured request, including raytrace=None. Regrade pays the same
actual-size sum in its retained request lease, independently of its presentation/
master lease and without duplicating source texture/HDR costs. Thus default
pixels/work/buffers stay identical, but its admission metadata estimate honestly
includes this sizeof delta; no previous layout is fabricated. Every new Sun stage consumes the existing
cumulative work ledger before mutation, and the next bounded host quantum observes
cancellation. None skips that stage and allocates no celestial heap state.

The common light editor saves/loads/filters finite Sun on either renderer. CPU
Sky is available from the Environment source picker only with explicit Indirect
lighting. Numeric load, Undo and environment edits preserve the shot camera.
When a Sun/Sky setup switches between CPU and GPU, its exact source values and
common rig are converted prospectively. Incompatible domains refuse atomically.
For GPU→CPU with no CPU Path, a separate reachable method action explicitly plans
Indirect depth, CPU progressive SPP/seed and traced shadows, then validates and
persists one Undo transaction. It retains the chosen CPU profile, adaptive policy,
presentation, lens and saved scene intent; it never raises a cap or clamps depth.
The same transaction includes an authored Atmosphere box, so a combined setup
never uses sequential effect writes or an obsolete GPU-only Volume refusal.
Atmosphere still refuses incompatible Glass/SSS, noise reduction and transmission
strata without clearing their values.

The published suites cover independent per-ordinal/energy cases, HDR addition,
complete PNG prefixes, raw FLOAT32 masters, lens/adaptive/certified-Glass routes,
map/aging closure, work/cancel and retained capacity, plus saved/common API and
pointer-UI fixtures. Native preview/final/export/reopen evidence for each such
optical combination remains separate. Results from an earlier binary or source
do not qualify a new implementation.