solvecraft/docs/render-primary-aa.md

Bounded primary spatial AA proposal (#620 / existing render-quality work)

This unit originated as a source port on the personal rendering branch's CPU/GPU2 snapshot. The combined CPU-feature renderer build, layout and numerical regressions have now executed. Current combined engine/UI/native qualification, performance and full-project validation remain separate gates. See advanced CPU integration for the exact source baseline and recovery provenance.

raytrace.primary_samples is the runtime option, also saved as CPU job.options.primary_samples: omitted/1 retains the legacy fixed-centre route,4 uses a2x2 pixel-box grid,16 uses4x4. Other counts refuse. Default1 is omitted from serialized options to preserve the default request representation. Typed CPU setup edits use the existing save/Undo path; GPU MSAA, material libraries and optical boundary definitions are independent. The integrated CPU image UI already exposes 1/4/16 primary samples; engine/MCP and the CLI's runtime raytrace options use the same request contract. This recovered follow-up changes the bounded reuse implementation, without adding a second saved AA authority.

The single-primary branch keeps its former generator, reuse proof, R addition order/divisor, primary-background shortcut, seeds, work debits and encoding. New modes complete ALL SR logical attempts, including primary misses and nonselected surfaces. The current fixed grid certifies repeatability only within one (pixel, spatial ordinal), so a completed nonselected PRIMARY hit may reuse its full direct/environment radiance across R. Each reused R still debits one cancelable scalar continuation, adds coverage once, performs the original ordered radiance addition and finite-bound check, and keeps the original divisor. Selected hits (including null reflections), secondary paths and primary misses retain the uncached route. A completed-state marker uses the existing bounded light cursor; no task fields, allocations or pools are added. The marker is cleared before the next spatial sample or pixel; it never crosses jobs. Future per-R jitter or other varying inputs must revoke the generator proof. The old blanket assertion forbidding every AA birth proof is replaced by fixed-ray invariance, distinct-spatial-ray, hit-classification and actual-consumer reference regressions; observable coverage, progress and refusal assertions are preserved. R remains the existing reflection attempt count (or1 with no active selections), bounded1..64. Null reflected continuations contribute zero and still count in R; they never erase primary coverage. Grid centres are strictly inside the pixel, fixed row-major, without jitter/temporal sampling or a progressive-prefix claim. New reflection keys use checked pixelS+s plus a fixed AA domain xor; the existing sampler receives the same reflection ordinal, bounce and R as before. No PDF or BSDF is changed.

For geometry hit indicator H and scene-linear path radiance L, C=sum(H)/(SR) and P=sum(L)/(SR). New modes compute conditional geometry radiance G=P/C, apply exposure/Reinhard once to G, then composite C*T(G)+(1-C)*decode(background) in display-linear sRGB before one sRGB encoding. All-miss pixels retain the exact background bytes; full coverage omits background operations. Background remains display-referred, not an emitter and not exposure-controlled. Do not averageRGB8, individually tone-mapped paths or tone the premultiplied P. Opaque output keeps alpha255; explicit transparent PNG exports straight RGB and rounded geometric coverage. Neither mode turns material opacity into physical refraction.

One ImageTask/PendingPixel/BVH/host pool and one cumulative1e9 WorkBudget remain. AA retains fixed scalar/Vec3 accumulators; reuse adds no fields. Per-R-add radiance limits remain unchanged; spatial normalized sums have a finite1e12 bound. Coverage is checkedu16<=1024. Separate spatial finalization and pixel emission states each debit work and yield; cancellation is checked again just before pixel bytes are emitted. Running progress still counts completed OUTPUT pixels. No partial PNG or samples reduced on exhaustion. Existing384MiB job/512MiB host limits and PNG encoder are retained. A compile-time type-length check and written layout regression require actual ImageTask<=4096 bytes; that guard passed in the combined CPU-feature build. Other feature/platform configurations retain their own validation gates.

Cost can grow with S*R, traversal, lights, HDR and bounces. Retaining exact intra-spatial primary reuse does not establish any work-budget success. Limits can refuse jobs that previously completed. No work/ray equality, speedup, smooth metal, universal antialiasing or final-mode claim follows. Thin/repeated geometry can still alias under fixed quadrature, and reflection noise is a separate issue.

Nine written regressions cover strict options/default serialization; grid and analytic discrete edge coverage; conditional tone/display-linear compositing; actual hit-first/miss-first half-plane traversal acrossR1/4/16/64 with nulls; all-miss bytes and quantum parity; full coverage; cancellation/work exhaustion in later spatial samples/finalization/emission; and S1 isolation/bytes/work with same caps/layout. The blanket birth-proof policy assertion changes as described above; existing observable assertions remain. New actual-consumer tests compare every ordered R accumulator prefix, logical coverage and PNG bytes with the same ImageTask route whose proof is revoked before its first shading completion. The renderer numerical and type/layout checks have executed. Current combined engine/UI/native and full-project acceptance remain pending. Default-vs-historical exact-build byte/work comparison, engine/host preflight validation, arbitrary projection scenes, allocation/layout and ownership gates, Clippy/wasm and required cargo xtask ci are required before publication. Designer must inspect actual equal-camera edge comparisons; source math is not visual acceptance. No external code/assets/dependencies were added.