titan-rendering-debugging

name

titan-rendering-debugging

description

Use when diagnosing a Titan renderer artifact — flicker, ghosting, fireflies, banding, light leaks, seams, boil, NaN/Inf, aliasing, smear/trails, dark voids, shadow artifacts, GI instability, denoiser/TAA issues. The frame-isolation-first debugging method: capture 60Hz, diff frames / A-B vs classical, consult literature, isolate via systematic-debugging, propose (and prove) a fix, record empirically. NOT for landing the production fix (hand to titan-rendering-3d-agent), 2D rendering, or editor panels.

Titan Rendering Debugging

The method for diagnosing a Titan renderer artifact. Stable; the empirical record lives in docs/rendering/RENDERING_BUG_HISTORY.md and the bench/instrument detail in references/.

Required skill chain (load all three, in order, every time)

1. titan-rendering-core — frame-graph, DevicePool, RenderTarget, HDR, tonemap conventions.
2. titan-rendering-3d — deferred chain, Stratum GI, ReGIR, SVGF/A-SVGF, TAA, shadows.
3. realtime-rendering-3d — generic real-time rendering literature + clean-room provenance rule.

These are hard dependencies. Skipping any = ungrounded work. The provenance rule from realtime-rendering-3d is load-bearing for IP posture (never paste proprietary source into committed files).

The debug loop

1. Reproduce + characterize. Get the artifact on screen with a known bench command (see references/bench-catalog.md). State what is seen, where, and under what motion.

2. Frame isolation FIRST (lead technique — do this before trusting any aggregate metric). Capture a 60Hz frame sequence and:

   • Diff consecutive frames to localize temporal artifacts (flicker, boil, swim, ghosting).
   • A/B against classical lighting (or against the feature toggled off) to localize which pass owns the artifact.
   • Test across MOTION REGIMES, not one frame — for any denoiser / temporal / sampling change, evaluate the static hold AND the rotation (yaw) at minimum (bench: static = Phase 6 t12.5–15; yaw = Phases 7–8 t15–25; dolly = Phase 4–5 t7.5–12.5). A change can be worse in one regime and dramatically better in another: 2026-06-05 the de-grid bilateral read as a null/slightly-worse on a static converged frame (temporal already did the work) but was a clear win during yaw (temporal reprojection is weakest in rotation, so the spatial pass fills the gap). A single-regime A/B can invert the truth. During rotation, per-frame frame-diff metrics are invalid (geometric motion dominates ~100:1) → use a frame-aligned side-by-side video (perceive-together) as the judge, plus per-frame within-frame spatial stipple (motion-free). Aggregate metrics (mean luma, global flicker score) are spatially blind to narrow artifacts, and per-frame magnitude metrics are blind to motion swim/crawl (the eye grades temporal coherence under motion, not per-frame std) — both have produced repeated misdiagnoses here (see RENDERING_BUG_HISTORY.md 2026-05-28 F2 seam; 2026-06-05 de-grid B). Per-ROI / per-pixel inspection and perceive-together beat a global number. Decay-at-fixed-cell metrics are additionally shape-blind: measuring temporal decay at a stationary probe cannot see a feature's centroid DISPLACEMENT — three rounds of trail toggle batteries were internally consistent yet missed the froxel-fog origin-shift reprojection bug (halos displaced 33–72 px; RENDERING_BUG_HISTORY.md 2026-07-14/15). The discriminators that work: single-frame shape/asymmetry tests + a MATCHED-POSE FROZEN CONTROL (TITAN_BENCH_FREEZE_T at the same timeline t, frozen arm pre-run ~2 s to converge histories — any frame diff at the identical pose is pure temporal state). Also split the motion regimes: a rotation-clean / translation-ghosting fingerprint points at a coordinate-basis (origin/re-anchor) defect in a reprojection, since pure rotation keeps the camera-relative origins coincident.

2b. Rule out global/shared passes before trusting a model- or branch-specific hypothesis. A symptom reported against one lighting model or one recent branch is not evidence the cause lives there — Pass::Tonemap and other model-agnostic post-process passes run downstream of every model/cell. Confirmed method (2026-07-15): an FFT of a suspect near-black ROI showed a strong periodic (176× mean-magnitude) non-DC spike — genuine ordered-pattern evidence, not an impression — that stayed byte-identical across two named suspects (a feature branch AND the commit either side of a merge under investigation) before it was traced to the final tonemap's ordered dither. When a cross-arm parity check (same command, same metric, all arms) comes back byte-identical, that is itself the confirming result — it falsifies both suspects and redirects to shared infrastructure, it is not an inconclusive non-finding to explain away.

2c. For any dither/quantization artifact, check the color-space ordering before the amplitude. The first fix attempt for the 2026-07-15 near-black speckle (tapering dither amplitude by luma) was a plausible-looking but WRONG mechanism — the real defect (found by a literature survey, not more measurement on the same axis) was that the dither was added in linear space before the GPU's automatic sRGB encode instead of after. Near black the sRGB EOTF's slope (~12.92) amplifies a linear-space perturbation by that same factor once the hardware re-encodes it — a ±0.5/255 dither becomes ~±6.4/255 in the visible output. Before proposing an amplitude-shaping fix for any dither/banding artifact on an auto-*Srgb render target, verify (a) the target format via Renderer3d::surface_format/surface_format_linear and which view the pass actually writes (some passes use an alternate linear view deliberately — egui does), and (b) whether the dither is applied before or after the linear→sRGB encode. Getting the color space right is orthogonal to getting the amplitude right, and a survey of the literature (Bevy/Godot/canonical GDC talks) will surface the space-ordering rule long before a from-scratch amplitude experiment would.

3. Consult the literature. Use realtime-rendering-3d for the canonical algorithm and its known failure modes. Match the observed artifact to a documented failure class before hypothesizing.

4. Isolate via systematic-debugging. One hypothesis → gather empirical evidence (frame-diffs, VIZ modes, dumped scalars, toggle A/B) → confirm or kill → next. Do not skip to a fix.

5. Consult the literature again to derive candidate fixes for the confirmed cause.

6. Prove the fix, then record + hand off. Prove a candidate empirically in a throwaway worktree (capture 60Hz + classical A/B + bench numbers), then DISCARD the worktree. Append a RENDERING_BUG_HISTORY.md entry. The production landing is titan-rendering-3d-agent's job, not yours.

Durable symptom patterns (consult before hypothesizing)

• Growing black regions / a whole-frame collapse to black under a MULTI-light stochastic sampler, where the SAME regime is fine with only 1 light = an unclamped WRS unbiased-estimator weight (W_out = w_running/picked_w), NOT a TAA/denoiser bug per se. With 1 candidate, W_out is trivially 1.0 (zero variance); with ≥2, it has real variance and can spike. If ONE consumer of a WRS/SampleRecord producer clamps the weight before use (a firefly cap) and a SIBLING consumer of the SAME producer does not, the unclamped sibling is the leak (2026-07-09, Lattice-Mid: lattice_shade.wgsl clamps to MAX_SHADING_WEIGHT; froxel_fog_inject.wgsl's lattice_active branch did not — NaN entered froxel_scatter/froxel_integrated, not the direct shade output). TAA (or any temporal accumulator downstream) will look like the culprit — --taa false "fixes" it, every TAA feature toggle fails to fix it — because it faithfully amplifies/exposes an already-corrupted hdr_intermediate, not because TAA owns the bug. Isolate by: (1) tapping the DIRECT lighting-model output (e.g. lattice_radiance_raw) for NaN/Inf — clean there means the runaway is in a DIFFERENT term composited into hdr_intermediate (fog/SSR/GI); (2) tapping every candidate composited term (fog-volume/froxel taps if present) for np.isnan().sum() directly — Reinhard-tonemapped PPM previews alone cannot distinguish "legitimately bright" from "NaN/Inf" (both saturate to 255); use TITAN_DUMP_LINEAR=1 for the raw .bin and check for NaN explicitly. A spatial (not just global-mean) check — a 16×16 grid occupancy map compared against the same-window 1-light control — reveals whether the corruption is a directional/spreading front (consistent with a per-voxel/per-cell producer) rather than uniform dimming, which a global mean/std metric alone cannot distinguish.

• pre-TAA tap is the denoiser-vs-estimator discriminator. --capture-target pre-taa taps the radiance_raw edge after StratumComposite, BEFORE TAA. If the artifact is ABSENT pre-TAA → TAA/denoiser owns it (e.g. 2026-06-20 static near-wall dark annulus = TAA YCoCg neighbourhood-stats corruption by a bright-core outlier; fix = depth/normal-gate the 3×3 stats, Bitterli 2020 §5). If the artifact is PRESENT pre-TAA → it is upstream (estimator / shadow / shading). Run this tap EARLY; it splits the pipeline in one shot and kills whole hypothesis branches.

• Concentric RING shadows / a dark-then-light halo as a light nears or passes THROUGH thin geometry = SDF sphere-march thin-occluder overstep, NOT reuse bias and NOT TAA. shadow_sdf_global.wgsl steps by max(d, MIN_STEP); the nearest-seed distance reports ≈voxel_size one voxel from a ~1-voxel wall, so a phase-dependent step jumps clean over it → iso-phase rings (2026-06-20, FIXED c5af38b8). Isolate: TITAN_STRATUM_SHADOW_TERM_DISABLED=1 (rings gone ⇒ shadow term), --denoiser-tier low (no SDF march ⇒ gone), TITAN_SHADOW_SDF_HIT_THRESHOLD_M sweep (rings→leak is the overstep tell). Fix = MAX_STEP clamp (clamp(max(d,MIN_STEP), MIN_STEP, vox*0.5), Nyquist / Quilez 2010) + forward-only golden-ratio-dithered march start. A dark annulus is the textbook ReSTIR biased-reuse signature (Bitterli 2020 §4), which makes reuse the seductive-but-wrong lead — the REGIR_DIRECT=0 + --stratum-spatial-reuse off A/Bs falsified it here. Run the falsifying toggle before committing to the literature's first match.

• --wall-pierce (probe) is the repro for through-wall shadow artifacts: camera held head-on 4 m from the wall, primary light swept in Z straight through the wall plane (crosses at the timeline midpoint). Decouples light-through-geometry from camera motion — far cleaner than the orbiting fleet.

• Area-light A/B arms (probe, 2026-07-16): --area-light swaps the scripted primary for a 2×1 m rect AreaLight (same color/intensity/range); --area-flux-point swaps it for the EQUAL-TOTAL-FLUX point arm (I = A·L/4 = LIGHT_INTENSITY/2 — one-sided Lambertian rect Φ = π·A·L vs isotropic 4π·I). Together they are the LTC rect-vs-point comparison instrument on --cell deferred-lattice (P2.5 acceptance evidence: broadened highlight px>0.7 luma 97k vs 12k, zero non-finite tap texels).

• Through-wall LIGHT LEAK (floor lit where a wall should shadow it) = the screen→SDF FORWARD-SKIP HANDOFF. shadow_screen.wgsl covers [0,2 m] then hands start_dist_m to shadow_sdf_global.wgsl, which skipped forward by HANDOFF_EPSILON_SCALE×voxel → flank dead-zone (skip oversteps real crossings) + center no-op (dist_to_light<2 m → SDF starts at the light → 0 steps). FIX = drop the forward-skip, full-march from a receiver normal-offset origin (render_pos + n×voxel) — the normal-offset is mandatory or the bare full-march self-occludes the whole floor (RAY_BIAS 0.05 m < 0.25 m voxel). Canon = Wright 2015 (R1/R3). MERGED 649c1cb3 (PR #25, perceptual gate ACCEPTED 2026-06-21 — the user accepted that R1+R3 reopens the grazing-corner over-occlusion; signed-SDF canonical fix is a future milestone). The five canon-ranged march params are now tier-gated RenderQuality knobs (MAX_MARCH_STEPS/HIT_THRESHOLD_M/MIN_STEP_M/ SDF_NORMAL_OFFSET_VOXELS/RAY_BIAS_M); TITAN_SHADOW_SDF_* envs override on top.

• SDF corner/grazing OVER-occlusion (false dark band; SDF-off recovers it) is an UNSIGNED-SDF DATA artifact, NOT a march-parameter bug. Titan's unsigned SDF + positive HIT_THRESHOLD false-hits grazing rays (parallel-near a wall, d>0 but <ε); Wright canon uses a SIGNED SDF with sign-crossing termination (d≤0 = inside) so grazing never false-hits. Tell: ALL march-side single-signal discriminators (distance skip, near-hit rejection, grazing normal-vs-ray) fail to separate the false corner hit from a real wall crossing — they are geometrically identical in the same cascade. That identity IS the signature that the fix is in the DATA (signed SDF / mesh-voxelized seeding), not the march. Don't chase distance/angle levers once they're shown to overlap.

• RETIRED (2026-07-11, P3.5 Task 5, commit dddbc81e): the 12-iteration wall-normal/dir-direction escape loop in march_shadow (shadow_visibility_sdf.wgsl) is GONE — do not look for it, and do not re-propose an escape-walk fix for a self-occlusion artifact at a concave corner. It was retired in favor of a per-tier self-occlusion START-GATE: NEAR_SELF_SKIP_VOXELS=2.0 (near-field per-mesh candidates) and GLOBAL_SELF_SKIP_VOXELS=4.0 (the global cascade, added by Task 5c after retiring the loop reopened junction false hits). If a wall-floor-junction false-occlusion artifact reappears, the first thing to check is whether the false-hit t clusters near K × cascade_voxel_size_m for either gate (round 22's decisive signature: the false-hit population RE-CLUSTERS at whatever the current gate threshold is, rather than vanishing at a fixed world-space radius — a re-arming artifact, not a fixed-radius contamination footprint a bigger constant safely clears once). A coordinate-space methodology trap cost 3 rounds (18, and implicitly 6/8/9) chasing a phantom "JFA +X-edge seed asymmetry": any diagnostic script that decodes the global-SDF cascade's origin/world_min fields must first subtract camera_world_pos from a raw world-space query position before doing origin/voxel-index math — those fields are RENDER-SPACE (camera-relative under LWC), not absolute world space (FrameUniforms's own doc comment says so). Feeding a raw world position directly into that math produces a self-consistent-looking but WRONG decode (a "bogus self-seed 1.5 m below the floor" that was actually a correct floor-surface seed at world Y=0.0). The canonical corrected decoder now lives at titan-dumps/global-sdf-decode/global_sdf_decode.py (gitignore-negated like edge-width-mtf/) — use it, don't re-derive the render-space subtraction from scratch. titan-render-bench-probe's TITAN_BENCH_FREEZE_T=<seconds> env freezes the camera at an exact timeline pose for reproducible per-texel cascade inspection across frames — useful whenever a static, fully-controlled camera pose is needed for cascade/GI-cache debugging, not just this investigation.

• A period-4/period-8 deterministic flicker (autocorrelation lag2 strongly negative, lag4 strongly positive, lag8 near-max positive, odd lags ~0) under an 8-sample Halton(2,3) TAA jitter cycle IS a known sequence property, not a coincidental phase alignment — verify with a quick offline numeric check (no GPU needed): compute the raw halton_2_3 x-sequence for n=0..7, take consecutive |Δx| jump magnitudes, and autocorrelate THAT series the same way you autocorrelate the measured |ΔY| series. The base-2 van der Corput bit-reversal recurrence has a genuine period-4 substructure in its per-step size (a carry to a coarser bit every 4th sample produces a bigger jump than the alternating pattern between the others) — this numeric control reproduces the SAME lag-2/lag-4/lag-8 sign pattern as the observed artifact (2026-07-13, confirmed to 2-3 decimal places) and is strong, cheap, independent corroboration before or alongside a GPU A/B. Isolate the mechanism by tapping the shading-model's OWN direct-light output BEFORE any denoiser/composite/TAA (e.g. lattice_diffuse_raw/specular_raw, not the swapchain) and freezing the jitter (TITAN_RASTER_JITTER =0) AT THAT TAP — a swapchain-level jitter-freeze test is confounded by GI/denoiser/TAA reacting to the now-static upstream signal with their own residual mechanics (2026-07-12/13 round's "raster jitter REFUTED" reading was exactly this confound; the direct-light tap resolved it to a clean bit-exact zero-delta proof). Candidate fix direction: a low-discrepancy sequence with a CONSTANT per-step increment (e.g. the R2/Roberts-2018 additive-recurrence sequence, public-domain, not proprietary) in place of Halton removes the jump-size periodicity by construction — tested 2026-07-13, real but partial swapchain-level improvement (lag8 ~77% reduced), not yet a full noise-floor collapse; see RENDERING_BUG_HISTORY.md 2026-07-13 entry for the full A/B. 2026-07-14 follow-up, load-bearing for any future TAA jitter-sequence decision: R2 is NOT a canon fork. The realtime-rendering-3d skill's own taa.md Pairing rules pin "pair the [jitter] period to 1/α" and name R2 as the canon-sanctioned choice when the accumulation window needs to be longer than an 8-tap Halton cycle can cover. Before treating a jitter-sequence swap as a divergence, MEASURE the actual 1/α at the artifact's ROI from taa.wgsl's own blend = clamp(1/(1+max(luma_curr,luma_hist)), 0.04, 0.5) formula (decode luma from an existing HDR tap, e.g. lattice_radiance_raw .bin, no new instrument needed) — a moderate-luma ROI (luma < 1.0) pins blend at the CEILING (0.5, N_eff=2 frames), not the floor, which is the OPPOSITE of "long window at a bright ROI" and means canon's own rule already calls for a period far shorter than 8. Also falsified this round: widening the accumulation window alone (Halton unchanged) does NOT collapse a period-N jitter signature — it leaves the target lag unchanged and smears correlation across every OTHER lag instead (the textbook broad-spectrum ghosting signature), because a linear EMA filter preserves an exactly-periodic input's normalized autocorrelation shape regardless of window length; only changing the source sequence's own per-step jump-size uniformity moves the periodic lag. See RENDERING_BUG_HISTORY.md 2026-07-14 entry for the full canon-check text, the falsifying A/B, and the yaw/dolly motion-regime validation.

• A per-frame-parity (period-2/4/8) content oscillation at a FIXED screen/probe position, surviving every reprojection/resampling/world-cache-content override, points at a Hammersley/van-der-Corput PLACEMENT jitter, not a lookup-indexing formula (2026-07-13, round 4 of the Lattice top-left-wall reflection asymmetry). Before assuming a periodic signature lives in a spatial lookup's indexing math, check whether that lookup's inputs even CAN carry a frame-dependent term under the repro's camera motion (a static-camera repro + TAA jitter confirmed to perturb only the projection matrix, never camera_pos, is a hard structural exclusion, no GPU needed). If excluded, the next suspect is any OTHER per-frame jitter feeding the position used by that lookup — e.g. a screen-probe/reservoir PLACEMENT pass's own canon-sanctioned per-tile jitter (Wright 2021 S37's "temporally jitter placement grid" for screen-probe GI) — at diagnosis time computed via a base-2 bit-reversal Hammersley(8), same sequence family as Halton; mark_uniform now reads a CPU-computed R2 offset from the place UBO (06c7169d), so this specific instance is fixed and the pattern applies to any remaining short bit-reversal jitter consumer. Freezing candidate content (e.g. TITAN_LATTICE_WC_FREEZE_UPDATE-style: clamp the frame index fed to the SUSPECT pass's UBO) and separately freezing the PLACEMENT jitter (clamp the frame index feeding the jittered pass instead) discriminates the two — content-freeze left the signature byte-identical, jitter-freeze collapsed it to a flat noise floor. This is the SAME root-defect class (non-uniform per-step jump size in a bit-reversal low-discrepancy sequence) as the period-4 TAA-jitter entry above, independently confirmed in a SECOND jitter consumer (probe placement, not TAA reprojection) — the fix pattern (swap for the R2/Roberts-2018 additive-recurrence sequence, titan_rendering_core::halton::r2_sequence) carries over directly. See RENDERING_BUG_HISTORY.md 2026-07-13 "Follow-up (round 4)" for the full isolation proof.

• A large, static (not periodic) magnitude asymmetry between two probes/texels that should be exact geometric mirrors, surviving every world-cache/clipmap-indexing exoneration, is a RESAMPLING EFFECTIVE-SAMPLE-COUNT artifact, not a lookup-math defect (2026-07-13, round 5 of the Lattice top-left-wall-reflection asymmetry). Before chasing floor()/voxel-index math further, check whether the pass reduces N independently-traced samples down to M<N via a "trace M, reassign/duplicate the rest" resampling scheme with NO importance-ratio reweight applied to the copied value — this quadruples (or worse) the variance of the per-probe aggregate against perfectly ordinary, non-bug per-direction geometric sensitivity (e.g. which of a fixed ray set clears a wall's finite edge), because the "winning" subset is chosen by an importance ranking that itself carries the same per-direction noise. Isolate by tapping the RAW per-texel atlas (not the tile mean) and checking whether nonzero texels come in exact multiples of the fan-out ratio (here, blocks of 4 — a 48+r/3-style 3-low:1-high reassignment) rather than a smooth gradient; confirm by toggling the reassignment off (if a debug override already exists for it) and checking the ratio collapses toward 1.0 at a frame-0 control (no reprojection/temporal contamination) before checking steady state (a self-referential resampling-target feedback loop, once already confirmed elsewhere, can still amplify the SAME root cause further at steady state without being a second, independent bug). See RENDERING_BUG_HISTORY.md 2026-07-13 "Follow-up (round 5)" for the full CPU-side wc_lookup_cell mirror-symmetry proof (floor-based voxel grids mirror as k ↔ n-1-k, not k ↔ -k — don't assume a naive negation is the correct mirror check for a floor-indexed grid) and the frame-0-vs-steady-state discriminator.

• VIZ-decode hazard: some scalar taps store channels LINEARLY in the .ppm, not Reinhard+gamma; applying the Rgba16Float Reinhard inversion to a linear channel gives a wrong reading (16× too small → a false "near-receiver" distance). CORRECTION (2026-07-11, round 22): sdf_march_debug is NOT an example of the linear case — round 2's own decode (this file, sdf_march_debug's repro command) and round 22's independent re-derivation both confirm it IS Reinhard+gamma-encoded (t=(s/255)^2.2; c=t/(1-t), then hit_distance_m=r*32.0, cascade_idx=round(g*4.0-1.0)). Confirm the tap encoding per-tap before trusting a decode; do not assume a prior round's hazard note names the right tap — cross-check against the shader's own textureStore write and a known-value sanity check (e.g. a cascade index that should round to an integer).

• A canon-conformance formula fix that REGRESSES a downstream artifact can mean the fix unmasked a pre-existing, previously-INERT consumer-wiring divergence, not that the formula fix itself is wrong. 2026-07-13, Lattice-Mid junction noise: correcting ShadingConfidence from a broken formula (pinned ≈1.0 almost everywhere) to the canon formula (genuinely low/noisy at poorly-sampled pixels) caused a 7.7× junction-noise regression — not because the corrected formula was wrong, but because a SEPARATE consumer (the TAA confidence port, blend = mix(1.0, blend, confidence)) had been wired to the WRONG pipeline stage's confidence (raw pre-denoise ShadingConfidence instead of the canon-pinned post-Resolve/post-denoise signal) the whole time — silently inert while the broken formula kept confidence near 1, and newly load-bearing (and wrong) the moment the formula got fixed. Tell: the regressing consumer already has its OWN comment citing the correct canon locus (here, "§4.1 step 15 Resolve") while its actual wiring reads from an earlier stage — a citation/implementation mismatch is the signature, not a deliberate deviation. Isolate by finding every OTHER consumer of the just-corrected value (grep the symbol, not just the pass that computes it) and testing each with a defeat-toggle before assuming the newly-corrected formula itself needs re-tuning. Falsifying/fixing test: neutralizing the SUSPECT CONSUMER alone (not touching the formula) must both (a) collapse the regression and (b) the collapse must be reproducible by routing the consumer to a genuinely different, still-varying signal from the stage canon actually pins — not merely by defeating the consumer outright (a defeat-only "fix" re-pins confidence to a constant, silently re-breaking the very formula correction that triggered the investigation).

• A "fast-update"/hysteresis-relax signal built from POSITION delta (hit-velocity, motion vectors, reprojection distance) reads a non-trivial baseline EVERYWHERE, not selectively near the actual fast- changing condition, when the sampling origin itself has intentional per-frame jitter (probe placement jitter, TAA jitter, stochastic ray origin offset) — freeze the jitter (a debug override pinning it to a fixed value) and re-measure BEFORE concluding the position-delta signal reflects real motion. 2026-07-13, GI EMA-lag follow-up: LATTICE_SCREEN_PROBE_FAST_UPDATE's hit-velocity metric read ~0.10-0.43 at EVERY probe in a static-hold scene, not just near the orbiting light — freezing the R2 screen-probe placement jitter (TITAN_LATTICE_PROBE_PLACE_FREEZE_JITTER=1) collapsed it to bit-exact 0.0 at all sampled probes, including each probe's own GI-radiance PEAK frame. A position-delta signal is structurally blind to "static geometry lit by a moving light" — the traced hit POINT doesn't move when only the incident light moves, so hit-velocity-based fast-update can never engage for exactly that scenario, regardless of tuning. The general lesson: before trusting ANY hit-position/ motion-vector-derived "something is changing fast" signal, confirm what it's actually differencing — if the position itself carries deliberate jitter, the signal's noise floor is set by the JITTER MAGNITUDE, not by the phenomenon you're trying to detect.

• A "fix" that shrinks a decay-length/temporal-lag metric is not proven correct until a causally- unjustified control (a blunt threshold tweak with no semantic tie to the hypothesis) is shown to NOT achieve comparable improvement, AND a static/unaffected-probe noise-regression check is run. 2026-07-13, GI EMA-lag follow-up: adding a radiance-delta term to LatticeProbeTemporal's fast-update reduced GI-decay amplification at 3/6 hotspot probes (e.g. 2.67×→1.67×) — but a control (radiance term neutralized, hit-velocity thresholds blunt-lowered so PLACEMENT-JITTER NOISE ALONE now trivially saturates fast-update≈1.0 everywhere) achieved COMPARABLE OR BETTER reduction at the same probes, with no causal justification whatsoever. Any change that raises how often an EMA's "fast" blend factor fires will mechanically shorten decay length, independent of whether the trigger is semantically correct — decay-length improvement alone cannot discriminate a correct fix from an indiscriminate "always relax more" hack. The needed second check: measure residual noise (e.g. std of the signal minus its own short moving-average) at a genuinely static/unaffected probe — both the targeted fix and the blunt control measurably regressed it here (+68%/+82% vs baseline), proving the "improvement" at hotspots was bought at a real, uncounted cost elsewhere. Always pair a decay/lag metric win with an unrelated-region noise check before calling a temporal-blend change a net positive.

Debug-tool durability rules (apply to every instrument you add)

1. Durable / reusable. No throwaway hacks. Build a VIZ mode, an env-tunable override, or a metric script the next session can re-run. Follow the existing TITAN_* VIZ-mode convention (see references/instrument-catalog.md).
2. Never in compiled / editor / release builds without explicit permission. Gate behind the debug-dumps cargo feature OR a TITAN_* env, default-off, zero-cost and DCE'd when absent. A no-feature build must be byte-identical with the instrument absent. If you cannot keep it out of the runtime build, STOP and ask before adding it. Watch the gated-off trap: an if FLAG {…} else {…} is NOT inert when FLAG is false — the else still runs.
3. Document on exit. Every new/changed instrument gets an entry in references/instrument-catalog.md (or bench-catalog.md) before the cycle closes.

Bug-history protocol

• Before diagnosing: read docs/rendering/RENDERING_BUG_HISTORY.md — the artifact may be known.
• After proving: append an entry using the schema there. CONFIRMED = isolation-proven only; everything else goes under UNCONFIRMED with its evidence gap. Empirical findings go to the bug-history; implementation-pattern / test learnings go to docs/agent-kb/titan-rendering-3d-agent/.

Pass manifest — first stop for per-pass I/O

Before hypothesizing about what a pass reads/writes, open docs/rendering/PASS_CATALOGUE.md (generated from crates/titan-rendering-3d/src/manifest.rs, debug-dumps-gated). It lists confirmed inputs, outputs, and dispatch kind for all 32 passes. Regenerate with:

UPDATE_GOLDEN=1 cargo nextest run -p titan-rendering-3d --features debug-dumps export

Full manifest invariants (catalogue design rules, verified pass order, SVGF defaults): KB docs/agent-kb/titan-rendering-3d-agent/sp-a-pass-manifest.md.

SP-D tap operator recipe (2026-06-03)

dump_stratum_stages and --dump-stages are DELETED. Use --tap / TITAN_TAP for all stage inspection.

Quick start:

# Tap diffuse temporal history + pre-firefly radiance, frames 60-65 only, once per id:
TITAN_TAP=diffuse_history,radiance_pre_firefly TITAN_TAP_WINDOW=60..65 TITAN_TAP_ONCE=1 \
  cargo run -p titan-render-bench-probe --features debug-dumps -- --cell deferred-stratum --denoiser-tier mid

# Bench CLI equivalent (TapArgs):
cargo run -p titan-render-bench-probe --features debug-dumps -- \
  --cell deferred-stratum --denoiser-tier mid \
  --tap diffuse_history,radiance_pre_firefly --dump-window 60..65 --dump-once --dump-label my-run

Env vars (SP-D additions):

env var	effect
TITAN_TAP_WINDOW=start..end	Half-open [start, end) frame window on absolute Renderer3d::frame_index. Supersedes TITAN_DUMP_AT_FRAME for range control.
TITAN_TAP_ONCE=1	Fire each selected id at most once per run. Keyed by id; fires exactly once.
TITAN_DUMP_SUBDIR=<name>	Output subdir: titan-dumps/<name>/{basename}-frame{N}.{ext}. Absent = flat.

Bench CLI flags (TapArgs, all 3 benches):

• --tap <ids> — comma-separated resource ids or "all"
• --dump-buffers — selects all 11 BUFFER_RESOURCES (union with --tap)
• --dump-window <s..e> — frame window on absolute frame_index
• --dump-once — single-shot per id
• --dump-label <name> — output subdir

Numpy decode by format:

format	decode
Rgba16Float (PPM)	Reinhard+gamma-encoded; PIL.Image.open(path) gives 8-bit sRGB
Rgba16Float (.bin)	np.frombuffer(open(f,'rb').read(), dtype=np.float16).reshape(H,W,4).astype(np.float32)
R32Float / R32Uint (.bin)	np.frombuffer(..., dtype=np.float32 / np.uint32).reshape(H,W)
Rg16Float (.bin)	np.frombuffer(..., dtype=np.float16).reshape(H,W,2)
Rg8Unorm (.bin)	np.frombuffer(..., dtype=np.uint8).reshape(H,W,2)
Rg32Float (.bin)	np.frombuffer(..., dtype=np.float32).reshape(H,W,2) — SP-D moments

Hook-internal tap ids (SP-D): radiance_pre_firefly, probe_field_viz, diffuse_history, diffuse_moments, diffuse_variance. Mid/High only for temporal ids; None at Low/Potato = silent no-op. SVGF temporal is diffuse-only. à-trous per-iteration: already tapped under diffuse_raw (no separate ids).

--dump-window is ABSOLUTE frame_index. Probe auto-maps --capture-start/end/fps to a matching window when --dump-window absent. Empirically: capture-start=1.0, fps=60 → frame 60.

Bench-probe traps (verified 2026-07-11/12, P3.5 campaign)

• The REAL bench-probe timeline duration is scene::TIMELINE_DURATION_SECS = 25.5 s — a binary/doc-comment elsewhere in the probe tool describes a stale 51 s scale. Any round-trip check ("does this capture window make sense relative to the full timeline") must use 25.5 s, not 51 s, or a window computed against the wrong denominator silently samples the wrong phase.
• --tap lattice_diffuse_raw/probe_diffuse reads all-zero unless the probe is told which diffuse-indirect source to use. Pass --stratum-diffuse-source probe explicitly — without it the tap's producer pass may not be the one actually feeding radiance_raw, and the capture silently shows zero rather than erroring.
• probe_field_viz's VIZ output needs TITAN_STRATUM_PROBE_VIZ set to match the CLI flag, not just the CLI flag alone — the env var and the flag gate two different things in the dispatch path; passing only one leaves the tap dark.
• A tap's .bin sidecar lands in titan-dumps/ (the dump-dir ROOT), not inside --output-dir. --output-dir/--dump-label control the .ppm/swapchain capture subdir; the raw linear .bin (TITAN_DUMP_LINEAR=1) always writes to the registry's own dump_dir() regardless of that flag — look in titan-dumps/ root first if a .bin seems to be "missing" from a labeled output folder.
• TITAN_BENCH_FREEZE_T=<seconds> freezes the camera at an exact timeline pose for reproducible per-frame/per-texel captures across multiple runs (used throughout Task 5c's rounds 18-22 to hold the same wall-floor-junction pose across frames 9 and 300 while checking for staleness/age drift).

SVGF engine defaults (verified 2026-06-02)

• atrous_passes default = 4 (NOT 5; changed at Artifact-A fix 2f19515b). Source: quality.rs:1003.
• σ_L default = 6.0 (NOT 4.0; raised at m49-l-cellflicker-fix-g). Source: quality.rs:1011.
• σ_L_specular default = 2.5 (NOT 1.5). Source: quality.rs:1012.

The bench-catalog.md table rows show the stale (5 / 4.0 / 1.5) defaults in the flag descriptions; the SP-E note at the top of that file documents the correct values. Trust the code (quality.rs) and the SP-E note, not the per-flag table defaults.

wgpu / naga gotchas

No installed wgpu skill. For wgpu/naga issues: known traps live in the KB (e.g. R8Unorm/R8Uint/ R16Float are NOT in the WebGPU baseline writable-storage set — use R32*; >4 storage textures per stage needs Limits::default() not downlevel_defaults()). For anything beyond, use WebSearch/WebFetch against the wgpu/naga docs + issue tracker and cite the source.

• draw_indexed_indirect with first_instance != 0 is silently dropped unless the device enables Features::INDIRECT_FIRST_INSTANCE. Signature: in a GPU-driven path that draws each cull/draw group with a separate indirect command carrying first_instance = group base, only the first group (base 0) renders; every 2nd+ group produces zero fragments. Decisive isolation = G-buffer depth tap (--tap gbuffer_depth …): the missing group's region stays at the cleared depth (1.0) = never rasterized, vs written = drawn-but-dark. Confirm by forcing first_instance=0 on all commands → everything renders. (2026-06-20, a2b679d3.) Enabled now, but watch for it on any new indirect path / a different device. Pairs with: cull AABBs must use the real mesh extent (group.mesh.aabb()), never a unit cube scaled by the instance matrix — identity-transform meshes (extent baked in vertices) otherwise cull against a 1 m origin box.

Anti-scope

• Landing the production fix → titan-rendering-3d-agent.
• 2D rendering / editor panels → out of scope.
• IP: never cite or paste proprietary engine source per the realtime-rendering-3d provenance rule.