Skip to content

ByteTerrace/Puck / .claude/skills/rendering

rendering

Verified

Maps Puck's SDF renderer and GPU code: mapCore, mesh bake, HLSL kernels, sdf-isa.hlsli, SdfOp, C#/HLSL layouts, world.shaders.reload, field scopes, GPU cost and occupancy. Sculpting: sdf-authoring.

FileKindSize
SKILL.mdskill md139.7 KB
evals/g02-ao-edit-has-no-effect/graders/ambient-is-a-separate-dispatch.mdmarkdown140 B
evals/g02-ao-edit-has-no-effect/graders/isolate.mdmarkdown84 B
evals/g02-ao-edit-has-no-effect/graders/reload-loop.mdmarkdown79 B
evals/g02-ao-edit-has-no-effect/graders/right-file.mdmarkdown96 B
evals/g02-ao-edit-has-no-effect/graders/skill-fired.mdmarkdown36 B
evals/g02-ao-edit-has-no-effect/graders/views-only-reads.mdmarkdown287 B
evals/g02-ao-edit-has-no-effect/prompt.mdmarkdown413 B
evals/g03-framerate-after-placements/graders/budget.mdmarkdown70 B
evals/g03-framerate-after-placements/graders/capacity-growth.mdmarkdown132 B
evals/g03-framerate-after-placements/graders/counted-work-not-wall-clock.mdmarkdown215 B
evals/g03-framerate-after-placements/graders/counters-gpu.mdmarkdown72 B
evals/g03-framerate-after-placements/graders/quality-knobs.mdmarkdown119 B
evals/g03-framerate-after-placements/graders/skill-fired.mdmarkdown36 B
evals/g03-framerate-after-placements/prompt.mdmarkdown371 B
evals/g04-hand-written-isa-define/graders/encoding-probe.mdmarkdown73 B
evals/g04-hand-written-isa-define/graders/generated-from-the-csharp-model.mdmarkdown138 B
evals/g04-hand-written-isa-define/graders/name-follows-the-enum-member.mdmarkdown135 B
evals/g04-hand-written-isa-define/graders/regenerate-verb.mdmarkdown98 B
evals/g04-hand-written-isa-define/graders/skill-fired.mdmarkdown36 B
evals/g04-hand-written-isa-define/prompt.mdmarkdown201 B
evals/g06-extra-map-call-sites/graders/each-site-is-an-inlined-copy.mdmarkdown110 B
evals/g06-extra-map-call-sites/graders/register-pressure.mdmarkdown74 B
evals/g06-extra-map-call-sites/graders/reuse-through-a-loop.mdmarkdown119 B
evals/g06-extra-map-call-sites/graders/rolled-loop.mdmarkdown65 B
evals/g06-extra-map-call-sites/graders/skill-fired.mdmarkdown36 B
evals/g06-extra-map-call-sites/prompt.mdmarkdown234 B
evals/g07-abi-change-with-reload/graders/both-sides-change-together.mdmarkdown103 B
evals/g07-abi-change-with-reload/graders/needs-a-rebuild.mdmarkdown113 B
evals/g07-abi-change-with-reload/graders/reload-compiles-kernel-sources-only.mdmarkdown118 B
evals/g07-abi-change-with-reload/graders/skill-fired.mdmarkdown36 B
evals/g07-abi-change-with-reload/graders/sync-pairs.mdmarkdown252 B
evals/g07-abi-change-with-reload/prompt.mdmarkdown192 B
evals/g08-dynamic-transform-capacity/graders/capacity-does-not-grow.mdmarkdown138 B
evals/g08-dynamic-transform-capacity/graders/fix-the-emission.mdmarkdown124 B
evals/g08-dynamic-transform-capacity/graders/identity-slot-is-a-bug.mdmarkdown117 B
evals/g08-dynamic-transform-capacity/graders/skill-fired.mdmarkdown36 B
evals/g08-dynamic-transform-capacity/prompt.mdmarkdown238 B
evals/g10-hard-op-in-one-kernel-only/graders/cpu-interpreter.mdmarkdown74 B
evals/g10-hard-op-in-one-kernel-only/graders/encoding-probe.mdmarkdown73 B
evals/g10-hard-op-in-one-kernel-only/graders/not-done.mdmarkdown71 B
evals/g10-hard-op-in-one-kernel-only/graders/parts-walk.mdmarkdown66 B
evals/g10-hard-op-in-one-kernel-only/graders/skill-fired.mdmarkdown36 B
evals/g10-hard-op-in-one-kernel-only/prompt.mdmarkdown144 B
evals/g12-hard-carve-reads-phantom-surfaces/graders/extend-the-carve-or-use-union.mdmarkdown141 B
evals/g12-hard-carve-reads-phantom-surfaces/graders/skill-fired.mdmarkdown36 B
evals/g12-hard-carve-reads-phantom-surfaces/graders/subtraction-exact-only-near-its-subject.mdmarkdown115 B
evals/g12-hard-carve-reads-phantom-surfaces/prompt.mdmarkdown217 B
evals/g13-hard-wrap-each-primitive-in-a-scope/graders/clamps-are-bounds-not-cost.mdmarkdown101 B
evals/g13-hard-wrap-each-primitive-in-a-scope/graders/make-the-primitive-lipschitz.mdmarkdown138 B
evals/g13-hard-wrap-each-primitive-in-a-scope/graders/scope-is-a-per-sample-cost.mdmarkdown88 B
evals/g13-hard-wrap-each-primitive-in-a-scope/graders/skill-fired.mdmarkdown36 B
evals/g13-hard-wrap-each-primitive-in-a-scope/graders/skips-early-out-and-rigid-planning.mdmarkdown110 B
evals/g13-hard-wrap-each-primitive-in-a-scope/prompt.mdmarkdown167 B
evals/g14-hard-two-lanes-both-added-an-op/graders/ci-checks-only.mdmarkdown122 B
evals/g14-hard-two-lanes-both-added-an-op/graders/fingerprint-rewritten.mdmarkdown100 B
evals/g14-hard-two-lanes-both-added-an-op/graders/generate-verb-or-build.mdmarkdown116 B
evals/g14-hard-two-lanes-both-added-an-op/graders/skill-fired.mdmarkdown36 B
evals/g14-hard-two-lanes-both-added-an-op/prompt.mdmarkdown207 B
evals/g15-signed-modulo-on-vulkan/graders/driver-answers-wrongly.mdmarkdown172 B
evals/g15-signed-modulo-on-vulkan/graders/lift-and-wrap-as-uint.mdmarkdown121 B
evals/g15-signed-modulo-on-vulkan/graders/skill-fired.mdmarkdown36 B
evals/g15-signed-modulo-on-vulkan/prompt.mdmarkdown353 B
evals/g16-per-pixel-field-view/graders/no-field-walk-in-a-pixel-kernel.mdmarkdown203 B
evals/g16-per-pixel-field-view/graders/sample-a-lattice-through-the-bake.mdmarkdown164 B
evals/g16-per-pixel-field-view/graders/skill-fired.mdmarkdown36 B
evals/g16-per-pixel-field-view/graders/slice-verb.mdmarkdown83 B
evals/g16-per-pixel-field-view/prompt.mdmarkdown311 B
evals/g17-new-bake-source-stale-meshes/graders/identity-follows-the-calls.mdmarkdown436 B
evals/g17-new-bake-source-stale-meshes/graders/names-mesh-identity.mdmarkdown70 B
evals/g17-new-bake-source-stale-meshes/graders/skill-fired.mdmarkdown36 B
evals/g17-new-bake-source-stale-meshes/graders/store-keyed-by-bake-identity.mdmarkdown175 B
evals/g17-new-bake-source-stale-meshes/prompt.mdmarkdown293 B
evals/moving-blend-crease-copies/graders/one-tuple-and-one-skin.mdmarkdown648 B
evals/moving-blend-crease-copies/prompt.mdmarkdown597 B
evals/shade-helper-cost/graders/one-admission-contract.mdmarkdown419 B
evals/shade-helper-cost/prompt.mdmarkdown312 B
references/authored-shading.mdmarkdown31.3 KB
references/gpu-cost.mdmarkdown37.1 KB
references/kernels.mdmarkdown34.6 KB
references/mesh-bake.mdmarkdown123.2 KB
references/mesh-gi.mdmarkdown64.6 KB
references/runtime-contracts.mdmarkdown26.7 KB
references/sync-pairs.mdmarkdown69.2 KB

references/mesh-gi.md

View on GitHub
# Mesh irradiance

The GPU relight, CPU reference and views shader share one probe lookup. Read this before
changing indirect light, probe visibility, the volume boundary or the camera sample. The exposure
meters each view's image (`SdfExposure.Meter`, the composite's histogram), never the volume; local
adaptation still reads the volume's gather at each surface.

`host.memory owners 0` reports the trace hierarchy under `sdf.mesh-gi.trace-scene`,
the arrays used to build it under `sdf.mesh-gi.scene-build`, and the CPU probe
volume under `sdf.mesh-gi.volume`. A geometry reused by two scenes keeps one
charge until its last scene releases it. A host refusal leaves the installed
scene available and the volume retries on its scene-build cadence. The GPU
upload retries its refused chunk before publishing the new root.

The software trace device law compares scene instance and original
mesh triangle ordinals through a diagnostic output separate from the hit words.
Hit/miss, material, normal bytes and back-face flags are exact; distance and
reconstructed position use a scene-scale FP32 bound with a grazing-incidence
factor (`SdfMeshIrradianceTraceDeviceLawTests`). A different triangle must itself
intersect within that bound; the law reports near ties and rejects more than
0.1% of rays. It also skips a top-level subtree and requires rejection on each
backend. Runtime trace, relight, selection and camera-sample queries use
`SdfMeshProbeGpuWork` on the residency's shared `SdfGpuWork` service on both
backends. CPU `TraceHits` and `Relight` remain reference/diagnostic paths;
placement still uses CPU nearest-surface and short clearance queries.

The trace device law also dispatches the production relight kernel with
miss-only cached hits and 32 shadowing directionals, isolating its any-hit
light bits. Every bit must equal CPU `Unblocked`, including the empty scene;
both that output and nearest-hit tracing assert zero overflow. Writable
fixture buffers are device-local, with explicit upload/copy/readback ordering.

Boolean visibility uses `sdfProbeOccluded` through the same `sdfProbeWalk` node
and triangle tests as `sdfProbeIntersect`, returning at the first accepted
triangle. `probeClear` uses that entry for shadows, light bits and the meter.
The CPU twin is `Unblocked` through `Walk` and `ILeaves` any-hit leaves.
`Hierarchy.BuildNode` bounds both hierarchies to `StackDepth - 2` edges from
the root, switching to median splits when only a balanced subtree fits and
refusing a named hierarchy that cannot fit. Walks check before pushing and
count `sdf.mesh-gi.traversal-faults`; CPU overflow also throws. GPU walks also
stop at `SdfMeshProbeTrace.MaxWalkSteps` node visits across both levels and
count the same assertion, so a single-child cycle cannot hang a dispatch. GPU jobs reset
and read the assertion word after the job's logical output under its fence.
The entry point supplies its generated result stride; retained slot capacity
can grow without moving that word or causing a readback of unused capacity.
The device law injects an overdeep hierarchy into a larger output allocation
and requires the assertion to count it on both backends. Reset copies use
`CopyWrite`, followed by shader read/write access for the atomic increment.
`puck mesh scene` reports top/geometry depth and forced median splits. The
degenerate-bounds scene law reaches depth 62 and compares nearest and any hits
with brute force, with zero overflow.
The scene command reuses `LevelsOf(High)` and `SdfMeshProbeDepth.RayDirections`,
so its comparison traces use the volume's actual finest window and quadrature.
Its `tree-hash` hashes the exported tree as the trace walks it, so a change
that claims to leave the scene alone compares base and head CLIs run back to
back over the same store (a booting World adds meshes to it). The scene's draws,
entries and top nodes are rented and go back to the pool at its last claim
(`SdfMeshIrradianceScene.Content`, shared with the `WithoutRetained` copy): a
new reader of a scene or its GPU export holds a scene claim for as long as it
reads, or it reads an emptied scene. The top level's braid order follows leaf
position, not the parallel build's node numbering, so a scene builds the same
tree on every run.
`world.budget` samples per-level median and maximum lighting ages when read,
in addition to the work-list cycle's combined ages.
Both work lists use the existing `Puck.Maths` three-way Morton interleave on
window-relative cells. Trace/relight class, lighting age and level retain their
priority; within each eight-cell radial band the order is spatial. A drain
still lists every cell and uses the same spatial order within each level.
For changing lighting, selection visits a stable cell phase every 1/4/8
completed sweeps by level. Phase uses the sweep ordinal, since lighting
versions can jump by a multiple of the period between sweeps and revisit the
same phase indefinitely. The sweep holds its initial phase
across empty or interrupted listings; a newer batch lighting never fills the
deferred phases within that sweep. A probe relit in the current sweep under
lighting since replaced is due at once, subject to its phase, so a lighting
change never waits for the sweep to end; a change within a sweep turns
interleaving on for the rest of it, and the next sweep interleaves too.
`SdfMeshIrradiance.OwesRelight` selects light updates on both paths. Missing
geometry, rebase and unwritten cells bypass the phase. The GPU validates each
selected hit allocation and decides whether its rays need tracing.
The worker lists again whenever the lighting version moves (`Work`'s
`m_listLighting`), rather than resuming a list made under the old lighting.
The bound is the authored age target times that level's interleave and is
reported in `world.budget`. A sweep beginning under the same lighting version
as its predecessor visits every phase so bounce propagation cannot stop on an
unvisited phase. The
CPU reference uses the same eligibility rule. A drain requests exact inputs for every cell and resets every bounce receiver.
Partial interleaved sweeps neither certify convergence nor consume the
full-window `MaxSweeps` limit.
The combined ages remain diagnostic totals; `behind` compares each level to
its own bound and reports the worst relative overrun. Its needed relight rate
is the sum of each level's probe count divided by that level's bound.
Relight priority puts overdue probes first, then lighting-stale ones, then age
relative to the level's bound before level, capture age and spatial band.
Overload can exceed the targets; no probe retires on its own small change.
The worker shares its time evenly between the list's traces and its overdue or
lighting-stale relights (`Work`, by the wall time each part's batches took), so
a lighting change is relit while a coarse level's first fill or a refill still
traces; the remaining relights follow the traces.
Below the bound, age priority is weighted by 1 inside any residency view's
frustum and 0.25 outside all of them, and by 1.25 when the probe's last relight
moved past the existing convergence threshold. Overdue probes ignore these
weights. Camera snapshots come from the same frame as the work snapshot;
elsewhere cameras are excluded because their coordinates belong to another
world. The diagnostic additionally reports the first view's counts, median
and oldest ages against those outside that frustum at each level.

The runtime retains geometry addresses in `SdfMeshIrradianceScene.GpuArena`,
in words of the shared `GpuRangeAllocator`. A replacement allocates its own
top hierarchy, braid entries and instance records, and only new geometry gets
uploaded. A worker packs these changed ranges into a bounded queue of
`SdfGpuWork.UploadChunkBytes` blocks. B1 admits their copies under its GPU,
host-time and byte budgets; `GpuRegion` remains the only uploader, with a
one-word CPU shadow and one staging slot per service slot. Chunk arrays are pooled
and returned only after their copy fence, or after cancellation drains the writer.
No hierarchy serialization runs on the frame thread.
`SdfMeshProbeGpuWork.TakeSceneUpload` excludes queries during replacement;
the old root and allocations stay intact until the new root's last upload
fence, then `CompleteSceneUpload` publishes and frees retired ranges. The root
is admitted only after the channel reports completion (all chunks read) and
every chunk fence retires. A stale scene cancels its writer; its obsolete prefix
is reclaimed after both writer and fences retire. Immutable geometry retains
fence-proven chunk progress in `GpuArena.Complete`, and the next export resumes
its remaining words, so repeated roster changes cannot restart a large geometry. Query
admission rechecks mesh residency and placement version after publication:
an intervening mesh relocation repacks instance addresses before any trace.
A changed mesh roster whose referenced vertex, index and material addresses
did not move owes no scene upload. The retained placement snapshot contains
only meshes that scene names.
`world.residency` reports completed scene changes, total payload bytes and the
last change's payload bytes, separately from staging allocation sizes.
Queries run several at a time across the service's slots (`SdfMeshProbeGpuWork`'s
`m_inFlight`), taken in submission order. A query that replaces, clears or fills
shared state (the hit cache, the camera-sample cache, the feedback volume's size, the
batch output) is exclusive: `TryTake` admits it only with nothing in flight and
admits nothing beside it, and a scene upload likewise starts only with no query
in flight. The scene and feedback regions stage through the taking job's own
service slot. Every job releases its readback when it is answered. GPU hit-cache allocations carry nonrepeating
tokens, checked by selection before reuse. The cache is sized to the published
tier (`HitCapacityOf`: the window's cells plus two fresh slots per probe a drain
batch places). A placed probe's trace job copies its hits into a fresh cache
slot on the device (the first trace and each trial into a slot of its own,
`PlaceBatch`); its relight adopts the slot it keeps (`AdoptGpuHits`) and the
cache pass stamps the token, so hits read back for the CPU's surface map are
never uploaded again. Placement traces every unresolved probe's next trials in
one round, doubling them each round from `FirstPlacementTrials` to
`MostPlacementTrials` within the cache's free slots, and keeps each probe's first
trial in order that lands outside; the CPU reference traces one a round and keeps
the same one. A batch's relight jobs each copy their results into the client's
batch output, and only the batch's last job commits every record into the
feedback volume, after the publication (`KeepsGpuPublication`) still stands as it
is taken and every earlier job of the batch ran; so every probe of a batch reads
the bounce the volume held before it, as the CPU reference does. The batch
lands only once that commit completed, then frame upload copies the ready slots
into the published GPU table. The CPU retains depth/sky and diagnostic lighting, and releases full
hit arrays once the batch is relit. Once the device has answered a camera sample, the camera sample reads
the GPU kernel's small answer rather than traversing the hierarchy on the frame. A job whose scene's meshes
are not resident within `AdmissionWait` is cancelled like an obsolete one, so it
never holds the coordinator or the camera sample behind it without bound.

A relight's GPU time is rays, not probes: each hit texel traces toward every
shadowing light that reaches the probe, and a probe that cannot reuse its
local cube traces toward every point light in range. `RelightGpu` predicts each
probe's rays and hands the batch to the probe service in one call, which cuts it
into jobs to background work's frame share at the relight's measured rate
(`RelightRaysWithinShare`): at most `RelightRaysPerJob` until a relight's
timestamps measure the rate (always, on a queue without timestamps), and at most
`RelightRaysCeiling` after. Every cut call (trace, select, relight) keeps up to
`SdfGpuWork.SlotCount` of its jobs in flight (`SdfMeshProbeGpuWork.Run`), sizing
each as it is submitted, so a call waits about one round trip through the frame
queue per slot-count of jobs. The service log's
`trace-jobs=[kind:jobs/units/latency]` (in `world.residency`) shows a volume's
jobs, their mean size and their latency from submission to answer. A batch cut by probe count
alone (384 fresh probes beside the stage, 78 point lights in range of each) ran
one dispatch past the device timeout. The walk's step bound bounds one ray, never
a dispatch. A slow job prints `[sdf.gpu-work] slow`, a device loss lists the
jobs in flight, and a job whose walks stopped at their bound prints
`[sdf.mesh-gi] traversal faults`.

`SdfWorldResidency.LightingPending` latches convergence after preparation for
the whole frame, including the final meter. `SdfWorldPasses.WaitingOf` feeds it
to render-graph completion. A worker finishing later cannot certify an image
whose exposure was held. Readiness waits for the next prepared frame. A held
frame shows nothing new, so its staging drives the service
(`SdfGpuWork.Drive`): the thread waits on the host, with a deadline, for a
job's fence or a client's offer, outside the budgets that protect a queued
frame, and the host's wait between frames steps the work the same way. The
drive runs inside the frame's open batch (the render graph stages residencies
after `BeginBatch`), so before each wait it hands its jobs to the queue
(`IGpuSubmissionFence.HandOff`): a deferred job neither runs nor wakes the
wait until the batch's flush, which holds a drain to a job a frame. A withheld
residency's top-of-frame pump is unmetered too (`SdfGpuWork.Pump`'s
`withheld`), and `SdfWorldPasses.WithheldOf` has the
render graph record no pass of the view again until the hold ends
(`IRenderGraphPackageFactory.WithheldOf`), so the drain has the GPU. A view
with no completed image still renders once. A residency no scheduled render
reads is not staged, so its drain waits until one does. `world.residency`'s
`gpu-work` line splits the drives' wall time into fence waits, waits for a
client and steps; fence time far above the jobs' measured GPU time means
something else holds the queue. A done line's `seconds` counts from the moment
the volume first owed work (`SdfMeshIrradiance.Owe`), not from the hold. A
settled PNG must have a capture completion line after the main residency's
done line; a nested residency's done line is insufficient.

An unheld frame meters the volume's work on the presentation's one budget,
ordered across residencies by what the player sees. A residency's service draws
by its frame's share of the display's pixels (`SdfFrame.DisplayShare`, a turn
in `SdfGpuWorkBudget.Takes`); a residency nothing read last frame takes
`SdfGpuWorkBudget.LeastWeight`. While a displayed camera has a cell awaiting its first publication at every
level covering it (`SdfMeshIrradiance.OwesFirstLight`, `first-light-owed=` on
the `[sdf.mesh-gi]` line), the probe service's jobs are owed work: they take
the owed allowance an arrival's bake work takes and the coordinator cuts them to it.
A glass's world measures only the levels its frame reads
(`SdfFrame.IndirectLevels`, from the presenting world's `render.nested`
`indirectLevels`; `measured-from=` on the `[sdf.mesh-gi]` line names the
finest): a finer level keeps its slots but is never listed, refilled or
published, the relight reads it at zero spacing, and a level the frame comes to
read again is refilled and republished whole.

| Part | Owner |
|---|---|
| Static scene and ray visibility | `SdfMeshIrradianceScene` |
| Volume coordination, CPU reference and bounce lookup | `SdfMeshIrradiance` |
| Device trace, hit cache, relight, selection and camera sample (`sdf-probe-camera-sample`) | `SdfMeshProbeGpuWork` |
| Probe record and generated shader constants | `SdfMeshIrradianceProbe`, `SdfIsaHlsl.DeclareRender` |
| Pixel gather, indirect light, reflections and traced-light visibility | `shade/sdf-mesh-irradiance.hlsli` |

- The scene hierarchy fills its packed seven-primitive leaves before adding
  another pair of boxes. Triangle tests keep their original precision. A
  geometry's nodes are 16 bytes (`PackedNode`): each bound is a 16-bit step
  count of its braid's frame (`BraidFrame`, the braid root's box), rounded
  outward by the one encoder, and `sdfProbePackedSlab` decodes it with the
  CPU's float expression, so both walks read one conservative box. The top
  level keeps float nodes. An entry names its braid's frame beside its node.
  Compare `puck mesh scene`'s hits, lit hits and mean distance after changing its
  storage or traversal, and walk the settled heap to measure retained arrays;
  working set includes temporary build storage and the mesh arrays as well.
- Keep `TryIncoming` and `sdfMeshProbesAt`/`sdfMeshIrradianceAt` together. A sky
  fallback in the CPU read feeds later bounce sweeps even if the final pixel
  read rejects it.
- Scene readiness is `SdfMeshPathBake.IrradiancePending`, not the whole bake's
  `Pending`: only opaque static groups enter the scene. An animated rebake,
  glass or a diagnostic slice must not postpone its first measurement or a
  refresh. A frame without lighting convergence builds a scene whenever what it
  holds for the static draws changed, paced by the trace (`ScenePendingDue`: no
  build running, the installed scene's traces paid or as many traced since it was
  installed as the windows hold, at least `PendingSceneInterval` since the last
  build began), and while opaque static groups are still pending it builds from
  those landed once one has (an empty scene would measure open sky where walls have
  yet to land), so the volume and the camera sample answer during a cold bake
  instead of after it. Waiting for the whole bake left every view
  `meter=none source=held` and every shaded face black for the ten minutes of a
  cold debug-world bake. A lockstep frame still waits for the whole bake.
- The scene holds each static placement's trace mesh, not the tier its view
  draws (`SdfMeshDraw.Trace`, from `SdfMeshPathBake`'s `Group.Trace` through the
  dresser): its bake group's floor, which the plan alone chooses, so a view's
  retier, the floor-to-first-detail swap and the budget's bias leave the scene
  standing. The key and the snapshot read `TraceDraws`, which takes a traced
  floor's pieces once a placement, at its first piece (`SdfMeshDraw.Piece`). A
  kept floor is traced until the trace judge (`SdfMeshTraceJudge`, on one pool
  thread from `SdfMeshPathBake.JudgeFloors`) holds it to the group's first finer
  product and declines it: every witness of each mesh must lie within
  `SdfMeshTraceJudge.Tolerance` (a quarter of the finest probe spacing) of the
  other, which catches a part the floor lost and a hole it closed or two surfaces
  it joined at that scale. A declined floor's group traces what it draws, which
  moves with the view again, and so does a group drawing a stand-in of another
  shape (an edit before its floor lands). `world.residency`'s floor line counts
  `trace-floor`, `trace-drawn`, `trace-admitted`, `trace-declined` and
  `trace-judging`, and each `[sdf.mesh-gi] scene` line its `floors`, the boxes the
  change named (`changed`, `all` for a change of every probe) and `held`, the
  seconds the built scene waited for a trace unit. The diagnostics measure the
  drawn meshes: `DiagnosticScene` returns the trace scene only where it holds
  them, and otherwise builds a scene of the drawn static draws on the pool.
- A scene built while the worker runs a listing or a batch (a trace unit,
  `BeginUnit`/`EndUnit`) waits in `m_pendingInstall` and is installed (`Install`,
  the one place the trace scene changes) when the unit ends. The batch lands with
  the geometry it measured, its queued GPU jobs are never cancelled for the
  scene, and the next listing decides from the change what traces again.
  `world.wait bakes` still waits for all geometry; an initial
  `world.exposure` reading with `meter=none` is not a backend-parity result.
- The volume has three levels (`SdfMeshIrradianceProbe.Levels`), a table per
  tier (`SdfMeshIrradiance.LevelsOf`, rows of `SdfMeshIrradianceLevel`: a
  spacing per axis and a window's dims): the tier's window, a storey level of
  4×2×4 m cells over 32×24×32 and a 32×12×32 window of 32 m cells, their slots
  after the finer levels' in one table, each described by a
  `meshIrradianceLevels` row (first cell, packed dims, ten bits each) and a
  `meshIrradianceSpacings` row (xyz spacing, zero until the level first
  publishes); `meshIrradianceVolume` is the enabled flag. Each level publishes
  as soon as its first slots land. Slots carry all three signed world-cell coordinates. Every rule that sizes
  by spacing takes the vector: `Lattice`, `Beyond` and
  `sdfMeshIrradianceBeyond` divide per axis, `SurfaceReachOf` is 1.5 cell
  diagonals, `Place` searches a cell whose half extent is per axis.
  A receiver's stages run finest first (`Select`, `sdfMeshProbesAt`): each finer
  level whose boundary probes' surface maps reach it past their window
  (`SdfMeshIrradiance.SurfaceReachOf`), then the level whose window holds it
  (the coarsest past every window) bounded, then available coarser levels for any missing corners, the chosen probes unbounded
  (`SdfMeshProbeDepth.Visibility(bounded: false)`: a miss no longer rejects a
  receiver past its reach, but a measured hit still blocks), then the finest
  level's boundary probes unbounded. The first stage that answers is chosen in
  its share: its weight over the same cage's front weight before visibility
  (trilinear × the facing fade without the behind floor, over every present
  probe, invalid ones included), clamped to one, and for a finer level past its
  window times its reach share (`ReachShareOf`, `sdfMeshIrradianceReachShare`):
  whole up to `SurfaceReachFadeStart` (half) of its reach, smoothstep to none at
  the reach, so the remainder takes over across a band instead of the one-row
  sawtooth a hard cut at `SurfaceReachOf` drew along walls
  (`TheFinestLevelHandsAReceiverPastItsWindowOverAcrossItsReach`). The rest comes from the next
  stage over another cage, normalized to the rest; a later stage of the chosen
  level reads the same probes and is skipped, so every receiver inside the
  finest window keeps one gather. Where no remainder answers, the chosen stage
  is normalized to the whole. The receiver reads sixteen slots
  (`SdfMeshIrradiance.GatherSlots`: the chosen cage, then the remainder's),
  pre-scaled so they sum to one; a traced static light's visibility is the
  weight of the lit slots of bounded stages. A shadowing directional (its
  `Shadows` flag) has a bit too, the probe's own ray toward it at the hits' reach,
  marked on every relight (`Relight`, a reused local part included, since a moving
  sun moves it): `sdfLightResponse` reads it wherever no cascade holds the point
  (`sdfShadowRoleAnswer`): past the cascades, blended across the band at their
  edge by the cascades' coverage, on glass, and in a view that draws none
  (`SdfShadeSurface.cascaded`: `meshShadowCount` zero, or soft shadows disabled,
  as `world.shadows off` and a nested view whose `render.nested` row drops its
  shadows are). The gather device law compares the sun's visibility on both backends. `world.probe` prints `level=`,
  `measured=`, `share=`, `remainder-level=` and `remainder-measured=`, and the
  remainder's eight corners after the chosen eight. An isotropic 8 m level could
  not resolve rooms a few metres tall: it had a probe plane in every other
  4.5 m storey, so the storeys between read one corner across a slab
  normalized to the whole. At the High tier the finest window about the middle
  of the gallery hall ends just short of its west wall (`body.pose 31.25 4.57
  28.52 273`, `world.indirect high`). A black or blown far wall is a level
  choice, which `world.probe` names, not a GPU/CPU disagreement. Never let a
  coarser level answer inside a finer window: at 25 m a 32 m probe's angular
  tap is metres wide, its patch test cannot resolve a thin wall the fine probe
  measured, and the wall law reads visibility 1 through it. A receiver with no
  answering probe never reads black: the extended stages answer far gallery walls
  and outdoor shaded faces past a window, and a receiver no stage answers reads
  the camera sample's light (`sdfMeshAnswers`, below).
  `SdfMeshIrradianceGatherDeviceLawTests` runs both gathers on one published
  volume and requires the same sixteen slots, weights, share and measured flags
  on both backends; `SdfMeshIrradianceLawTests.FarField.cs` holds the four-storey
  hall's segment-test counts.
- Each level's window centres on the box of the cameras of every view the
  residency renders when the box fits in the window's middle, and on the first
  view's alone when it does not (`WindowLow`). For the finest level the first
  view's camera is taken a quarter of the window's horizontal extent ahead of
  it along its horizontal forward (`WindowAnchor`); the coarser levels' windows
  already reach past the finest one's ahead. Centred on the camera, the Medium window ended 32 m ahead, and a
  view down level 1's hall from its west end read the far ceiling and floor from
  the storey level, whose 4 m probes 1.75 m under the ceiling see it past the
  hanging strips at grazing angles: jagged dark streaks beside each strip, and a
  floor 2 to 3 times too bright under the lamps. The first camera itself stays
  in the middle too: the window keeps its place only while the camera, its
  anchor and the views that fit all stand in the middle, and a recentred window
  shifts as little as puts them all there (`WindowLow`, `Centre`). Turning in
  place moves only the anchor, so the window recentres only as the anchor leaves
  its middle (about every third of a turn); walking backward recentres before
  the camera nears the back face (`TheFinestWindowKeepsItsCameraInItsMiddle`).
- A cold bake with `world.wait bakes` still pending, `sdf.mesh-gi.scenes=0`,
  and skipped `sdf.world$mask`/`sdf.world$bake` work is not by itself a stall.
  Read the wait's bake description twice: its meshes, pending groups,
  dispatches and samples distinguish progress from a stopped scheduler.
  A cold bake whose draw count keeps rising without finishing can be starved
  by simulation catch-up: `host.frames` shows several catch-up steps a frame,
  and `world.rate pause` on the boot instance restores frame time and bake
  progress. Pause only a
  diagnostic run, never the owner's play session, and disclose that change
  when comparing times. A nested world's `[sdf.mesh-gi] done` does not certify
  the gallery: check the main residency's counter and meter too.
  The scheduler's separate saved-pose/input-capacity defect has a focused
  boundary test; it is not the established cause of this slow gallery boot.
  See [mesh baking](mesh-bake.md#groups-poses-and-materials).
- A probe's geometry is one hit buffer (`SdfMeshProbeDepth.TraceHits`): one
  closest-hit ray per 12×12 octahedral texel at full reach, each hit an FP32
  distance (negative for a back face, infinity for a miss), its material and its
  normal's two signed octahedral bytes. Everything geometric derives from it:
  the six sky shares (misses, weighted by each texel's solid angle and cosine,
  `SdfMeshProbeDepth.RayWeights`), the inside share (back faces), and the
  surface map views test receivers against (`SdfMeshProbeDepth.Surfaces`): the
  hits within `1.5 * sqrt(3) * spacing + NormalBias`, FP16 distance beside the
  normal bytes, a negative distance marking a miss within that reach. Receivers
  beyond that measured support receive nothing. There is no second ray set. The
  hits are traced once per geometry (a scene build, a layout or reach change, or
  a cell new to a window) and never for a light change.
- A probe's light is a relight of its hits (`Relight`, `Shade`): the radiance
  cube, the sky-light cube and the traced-light bits, shaded under the current
  lighting. Every texel whose ray missed carries the sky's mean radiance over
  that texel's solid angle (`SdfMeshProbeDepth.SkyRadiance`, 4×4 samples of the
  lighting capture's sky map, the sky gain applied; the relight's
  `SdfMeshProbeRelight.SkyRow` table on the GPU) into the sky-light cube with
  the same cosine weights as a hit, so the indirect light a receiver reads
  (`sdfMeshIndirect`, `TryIncoming`) is the two cubes summed. The sky shares stay
  geometric and weigh only the reflected environment and the meter's open share.
  Never multiply a share by the hemisphere's SH irradiance for diffuse light:
  the sky's radiance and its occlusion are correlated (the horizon is bright,
  the ground below it is geometry, a window low in a wall sees the horizon), and
  the product read a north window's light at about half the path-traced value
  while reading the lawn through the same window exactly. The
  lighting version advances on a change of the directional or traced lights,
  the gains, the sources, the bounce switch, the scene's materials or the sky
  (the packed sky's key, then the sky texels themselves: `Lighting.SkyMatches`
  compares exactly what the relight and the meter read, so a kept capture never
  holds texels a replacement would change). `render.indirect.lightingGrid`
  authors direction steps in degrees and fractional radiance steps; zero is the
  neutral engine default. `SdfIndirectLightingGrid` snaps the directional records
  once for both the key and capture. The sky texels share a quantum per colour
  channel, anchored to the current channel peak's power-of-two range; tiny
  texels do not each trigger a new capture. These are functions of the
  current frame, never the last capture. Gridded lighting uses this policy in
  both modes. Asynchronous captures also observe the wall-clock capture interval.
  Converged sky comparison is exact, with or without a grid. Only continuous
  asynchronous skies retain `SkyTolerance` against the preceding capture, per
  texel and channel relative to that texel's own value, so a probe that sees
  the sky through a few rays still relights when those rays' sky changes.
  A relight's bounce reads the volume about each hit as it stands, so
  the bounce iteration visits probes with front-facing hits. A probe with only back faces and misses reads no neighbours. Another sweep follows while any probe of the last moved past
  `ConvergedShare` (plus `ConvergedFloor` nits) in any colour channel of any
  axis of either cube a relight reads (`Moves`: the radiance and the sky light,
  so an open probe whose sky light alone changed still owes the sweep its
  gatherers relight in), or was relit under a lighting since replaced; it stops only when a
  whole sweep under unchanged inputs moved nothing, or after `MaxSweeps` (an
  `[sdf.mesh-gi] unconverged` line). Convergence is never a probe's own: a
  probe that read zero before the light reached it is relit by the next sweep,
  and a geometry change wakes every probe. Never retire a probe on its own
  small change (the baffled-rooms and red-to-green laws in
  `SdfMeshIrradianceLawTests.Relight.cs`). A switched-off lamp's bounce decays
  over the sweeps, under a thousandth of the lit value in the point-light law.
  `render.indirect.bounces` zero switches the bounce off; any other value
  switches it on.
- The worker returns, never spins: when the budget leaves a probe's trace
  unfunded it waits for the next grant, and a lighting-converged frame asks it to yield
  at its next batch and its drain takes over its work (`m_yield`, `AwaitYield`, the spent-budget law).
  One worker task runs at a time, the drain included, so the worker's scratch
  (`m_candidates`, `m_results`, the GPU arrays) has one owner.
- The cube is two parts. The local part (the traced point and spot lights'
  bounce under their shadow rays, and emission) is kept per probe with the
  lighting's local version, which advances only when those lights, the gains,
  the sources or the materials change; a relight under a moving sun reuses it
  and traces no shadow ray toward a point light. The directional lights and the
  bounce are shaded every relight. A probe rebased across a scene change (its
  hits kept) keeps its local part too unless a change since its relight reaches
  one of its point-light shadow segments (`ReusesLocal`, the one rule for the CPU
  and the GPU relight): every hit lies within the probe's recorded reach of its
  origin (`ProbeData.Reach`), so a light's segments lie in the box about that
  sphere's part inside the light's range, the light and the origin, which is
  tested against the changes (`MeetsChange`). `sdf.mesh-gi.local-kept` counts the
  relights that kept it across a change. `world.probe`'s volume line prints
  `lighting-version` and `local-version`.
- A scene build records a box hierarchy over the world boxes of the static
  draws it added or removed (`ChangedBoxes`, `ChangeTree`, built with the scene's
  own `SdfMeshIrradianceScene.Hierarchy` and laid out depth first with escape
  indices, so a walk needs no stack). A probe traced against an earlier geometry
  is retraced only when one overlaps its placement region (the cell ± 1.5
  spacings and the clearance) or meets one of its rays before the hit the ray
  recorded (`Affected`, with a millimetre margin so a hit on the draw's own face
  counts); every other probe keeps its hits and is relit. The walk skips a
  subtree that neither overlaps the placement region nor comes within the
  probe's farthest ray (`ProbeData.Reach`), so a wave of thousands of swaps retraces
  only the probes its draws reach. Past `MaxChangeLeaves` a change's subtrees
  below `CutDepth` stand as leaves of their bounds, which name more probes but
  never fewer. A layout or reach change, a draw with no box, or a probe older
  than the last `MaxChanges` changes retraces.
- A selection is cut like a trace (`SdfMeshProbeGpuWork.Select`): jobs of
  the probes whose expected tests (`SelectTestsOf`: a ray walk per hierarchy
  level of each newer change) fit the live frame allowance
  (`SdfGpuWorkBudget.FrameAllowanceSeconds`) at the measured rate, each answered
  before the next is submitted. `sdf-probe-select` reads the rows
  `SdfMeshIrradiance.WriteChanges` packs: a row a change, then two a node.
  `most-job` prints a selection's `changes`, `change-nodes` and `tests`.
- Four reflected angular taps reconstruct local surface patches from first-hit
  positions and signed octahedral normal bytes. Join taps only when their normals
  agree and the symmetric point/normal residual is within `DepthSurfaceJoinGap`:
  opposite faces and separate parallel walls stay separate. Interpolate a patch's
  positions/normals before testing the signed receiver gap; extending each tangent
  plane separately shadowed visible curved receivers (the sphere law is red at
  visibility zero on that implementation). A sparsely sampled curved surface
  also needs its normal gradient. During the first sweep, fit curvature from
  compatible points/normals in each texel's reflected 3×3 angular neighbourhood
  and store one FP16 value per texel; an unsupported neighbourhood stores NaN.
  The gather interpolates compatible local quadratic coefficients and intersects their entering root along
  the receiver ray. Testing only a tangent/chord plane returned 0.574 visibility
  for an exact-segment-visible receiver in the small-curve witness. An unsupported
  tap casts no blocker; a distinct local hit supports the normal-gradient fit.
  At the finest level, once a tap blocks the receiver, a tap whose ray (at its hit,
  or at the receiver's distance for a miss or a farther hit) still stands on the
  probe's side of that blocker's tangent plane, or on it within
  `DepthSurfaceJoinGap`, carries no evidence and leaves the coverage in the measure
  the blocker closes the receiver (`SdfMeshProbeDepth.Unresolved`, the second loop
  of `sdfMeshProbeDepthVisibility`): it never got past the blocker. A ray that
  crossed the blocker's plane clear keeps its weight, so a receiver still eases
  over a texel past a finite block's edge. Counted as clear, an outdoor probe's
  ground taps in front of a wall's base, and its taps running clear past the end
  of a wall it sees at grazing, light the inside of the wall's foot and of a room's
  corner with sky: at Medium, a fifth of the gather of Wonderland's floor along its
  north wall and a quarter of its west wall's beside the north-west corner. The
  coarser levels close walls on sheets instead; there the rule would close the far
  slope of a hill their metres-wide taps see past its bulge
  (`TheCoarsestLevelKeepsACurvedSurfaceItSeesLit`).
  Curvature zero retains the exact plane intersection. The common-plane fast path
  reduces that same quadratic to one signed gap and reuses the decoded normal,
  avoiding four general fits in CPU bounce reads and pixels. Fade a patch over
  `DepthSurfaceFade` (2 cm, less than normal bias), then combine its blocked angular coverage.
  The flat-surface law also rejects radial-distance interpolation: it returned
  48% visibility for a coplanar receiver at radius 1.2 m and angle 89 degrees.
  No radial moments or squared-distance field remain. Misses supply no blocker.
  Blocked taps close by one rule a level (`SdfMeshProbeCoverage.Visibility`,
  `sdfMeshProbeCoverageVisibility`). At a coarser level the taps on solids close
  from half to three-quarter support, so a metres-wide minority hit cannot extend
  a finite block over the footprint, times the taps on sheets from zero to an
  eighth. At the finest level the taps on solids close smoothly over their whole
  share (`DepthFinestCoverageStart`, `DepthFinestCoverageScale`), so a probe's
  weight changes across a texel as the receiver passes a furnishing's edge. The
  finest probes stand among a room's furnishings (level 1's 2 m lattice puts a
  plane 0.45 m over the floor, below the gallery's plinth tops); the majority
  ramp, closing over a quarter texel, turned each such probe's view past a
  plinth into a hard-edged wedge across the floor and the faces beside it,
  wherever that probe's light differed from its neighbours' (the floor under a
  strip reads 1.6 times the floor between strips, as a line source's cosine law
  predicts). The residue is a soft wedge where a probe stands just behind a
  furnishing's edge (`world.probe` names it with `reference-clear=0`): a point
  probe there is truly blocked, and only a probe of finite extent (a penumbra
  over its cell) would blend it out. A coarse level's
  trace (`SdfMeshIrradianceLevel.Sheets`) marks a hit a sheet in the low bit of
  its texel's curvature half (`SdfMeshProbeDepth.Surfaces`; every reader masks
  it off before decoding the curvature) when the scene holds another surface
  within 0.45 × `DepthSheetThickness` (2 m) of the point half that thickness
  behind the hit: a slab, a wall or a slab's edge. A hill's near bulge reads only
  its own surface there. Each measured case decided the rule: the conservative
  ramp on every 32 m tap closed 254 of 1,439 exact-clear corners on the CPU test
  hills (`TheCoarsestLevelKeepsACurvedSurfaceItSeesLit`), the tolerant one let 238
  answering 32 m corners light the four-storey hall through slabs
  (`ACoarseProbeAnswersNoReceiverAcrossASlabOrAWall`, `far-exact-blocked`); the
  sheet rule leaves 6 and 18. A thickness measured along the normal alone read a
  slab's edge 12.6 m thick and left 126 of those leaks. The finest level marks no
  sheets: marking them closed a receiver beside a 0.15 m hanging panel
  (`AFiniteBlockerShadowsItsOwnDirectionsAndAWallStopsTheFarProbe`).
  `ASurfaceMapMarksASlabASheetAndAHillsNearSideASolid` checks the marks.
  `Affected` extends each ray by the sheet thickness, so a change behind a hit
  retraces the probe. Tests remain confined to these four
  angular taps: no 26-ray whole-sphere planes, neighbour separation, suspect sets
  or cross-probe vetoes return. Keep `SdfMeshProbeDepth.Visibility` and
  `sdfMeshProbeDepthVisibility` together, including signed normal decoding,
  seam reflection, patch compatibility, gaps and coverage. Projection/addressing
  reuse `SdfOctahedral` / `field/sdf-octahedral.hlsli`.
- Gather weight is the cell's trilinear share times
  `max(smoothstep(0, |spacing * normal| / 2, dot(normal, probe - receiver)), BehindShare)` times depth visibility.
  This continuous positive-hemisphere weight turns down probes behind a surface
  without switching the whole gather between front and back sets. It also
  prevents grazing depth uncertainty behind a thin wall from admitting a bright
  exterior probe. The floor (`SdfMeshIrradianceProbe.BehindShare`) applies at
  the finest level alone, whose depth test resolves the receiver's own surface;
  a coarser probe behind the receiver's plane is as likely beyond the receiver's
  own wall, and the gather's normalisation would let one such probe light the
  whole receiver with the outdoors. The floor keeps a
  receiver whose every visible probe lies behind its plane from reading black:
  a downward rim at the ground (a root, a shrub's underside, a fern's base) has
  only the ground-hidden probes below in front of it, and without the floor both
  gather passes summed to zero. `world.probe x y z 0 -1 0` just above the ground
  reads `answering=0` when that regresses.
  Squared angular cosines gave probes relocated close to a floor a strong pole
  directly above each lattice centre; the distance fade removes those repeated
  floor spots without changing the stored lighting. Past the boundary, blend
  this distance fade toward one over the first cell outside, as below. The CPU
  bounce read and pixel read use the same rule, without squaring the final weight.
- At the volume boundary clamp the lookup, then test the actual receiver,
  pushed `NormalBias` (0.05 m) along its normal, against depth. Never bias by
  spacing or test the clamped position: either can carry a receiver through a
  thin wall. An unwritten or invalid probe contributes nothing. A depth miss has
  finite reach in the measured read; the extended read (above) drops only that
  bound.
- Past the boundary the facing term eases to one over the first cell outside
  (`outside` in `sdfMeshProbesAt` and `Gather`). Every boundary probe lies on the
  window's side of such a receiver, so the hemisphere weight would light only
  the normals turned toward the window: a body or surface out there reads half
  dark, split at the plane that faces the window. Reproduce a boundary finding by posing beyond the coarsest window during motion.
  This easing applies only past the coarsest window, the one level a receiver
  outside reads; inside it the coarser levels supply far-field coverage, and the
  extended read lights a receiver past every probe's reach.
- Read `world.probe <x> <y> <z> [<nx> <ny> <nz>]` for each corner's origin,
  offset, back-face share, validity, sweeps, cubes and weight terms.
  Each valid corner also reports an exact mesh-segment `reference-clear` check,
  for diagnosing depth sampling separately from the lighting stored in its cube.
  This reference never changes the gather. A changing trace or pending publication reports `unsettled`, with both the
  published GPU window and live CPU window, rather than reporting the replacement
  cache as the rendered volume. Take lighting-finding captures only after bakes
  and irradiance settle; lockstep drains the window before rendering.
- Judge a visibility change at the `finding-sphere-step` and `gather-*` tour
  stops in `indirect` and lit views on both backends. Use the same fixed camera;
  a chase view without recentering can face the opposite way after teleporting.
  Include the boardroom's far doorway, stairwell flight B and teal roof/floor.
  Compare the settled GPU volume, exposure and frame time as well as pixels.
  Settlement means the configured sweeps finished, not global convergence of
  every cached cell. Match the visit order and record the published window:
  completed cells retain their measurements when a move adds new cells, and
  bounce reads use the current cache clamped to that window. A full tour and a
  direct teleport need not have the same bounce history.
  Match the executed camera commands too: replacing an unanswered input recenter
  with `view.recenter 1` resets the authored orbit/boom and can reverse a chase
  view. Recapture the baseline with the same measured commands before attributing
  those image differences to lighting. Explicit camera eyes/targets avoid this.
- The camera sample (`SdfMeshIrradiance.TrySampleCamera`) checks each probe's visibility from the
  camera through the existing scene. A plain trilinear interpolation reads the room across
  a thin partition when the camera approaches it.
- When none of the eight probes answers, the sample traces a hit buffer at the
  camera with the same rays as a lattice probe and relights it with the same
  materials, shadow tests and bounce cache. A hit no probe answers then reflects
  the sample's own light about its normal, iterated
  `SdfMeshIrradianceProbe.CameraSampleClosurePasses` times
  (`SdfMeshIrradiance.CloseCameraSample`, the closure in
  `sdf-probe-camera-sample-stage.hlsli`): the sample stands for every surface no
  probe answers, so its own unanswered hits read it as those surfaces do. An
  emissive strip reaches a wall only by bounce, so an unclosed sample of a room
  the volume has not measured holds its walls near black beside a doorway's
  sunlit ground at full strength, and every unanswered surface in the room takes
  the doorway's colour (the gallery hall from its lobby reads olive). A small enclosure may contain no
  lattice centre; searching farther or holding the previous room's exposure
  cannot measure its light. The hits are cached by camera cell and geometry,
  with at most one slot per view, and relit when the lighting version changes
  or the volume settles. Looking around reweights that measurement; moving
  within its cell reuses it only when the scene sees the camera from the
  sample's actual origin. A blocked segment requires a fresh measurement, even
  within one cell. `world.counters sdf.mesh-gi` counts `camera-traces` and
  `camera-relights`; a moving sun adds relights, never traces.
  At a camera cut the sample reads `fresh`: a sample is reused only from the very
  position, so the sample after a teleport depends on where the camera stands,
  not where it stood. `SdfViewExposures` keeps a cut owed until a sample
  arrives. The runtime samples on the GPU
  asynchronously (`ScheduleGpuCameraSamples`, at most every `LightingInterval`, at once
  after a cut): each view reads its own latest row wherever its camera now
  stands, so a moving camera stays `probes` or `camera-trace`, never `held`; a
  `fresh` read answers only from a row asked after the view's cut revision.
  The device meters only once it holds the volume's scene, which uploads after the
  scene is built and shares the background upload budget with the mesh region's
  landing (the debug world's scene is hundreds of megabytes), so it answers seconds
  into a boot. Until the device first answers, `TrySampleCamera` takes the CPU trace
  above on the built scene (`TryTraceCamera`), so a view's open sky is known from the
  build on. Before any sample a view reads the open sky (`airLight` one): a closed
  room then lights as daylight, the image meter settles near EV 13 instead of 7, and
  a 150-nit display reads black beside the walls. A screen that reads black only
  early in a boot is this, never its source: check `world.exposure`'s `camera=`.
  This camera sample never writes the volume or relaxes surface visibility.
  If the scene is unavailable or the camera is inside opaque geometry, retain
  the previous sample's light and sky visibility. `world.exposure` names the sample's source as
  `camera=probes`, `camera-trace`, `held` or `none`, and for `held` or `none` what it
  waits for (`wait=`, `SdfMeshIrradiance.CameraSampleWait`: `scene-build`, `scene`,
  `scene-upload`, `unpublished`, `camera-sample`, `unasked`, `cut`).
- A settled frame with no opaque static draws installs an empty scene and
  retraces its probes against open space. Empty is known geometry, distinct from
  a scene not built yet; removing the last draw must discard its occlusion and
  bounce light, even when dynamic or glass draws remain.
- A geometry or lighting change never clears the cache, and no landed batch is
  thrown away for a lighting change: a batch takes the latest lighting and
  lands whatever version it relit under. The worker (`Work`) lists the windows'
  probes that lack a trace against the current geometry (finest level and
  nearest first), then those whose lighting is stale or whose bounce has not
  converged (oldest lighting first), and works through the list a batch at a
  time while the budget (`render.indirect.budget`, `SdfIndirectBudget`), a rate a second of wall time whatever the frame rate,
  grants relights and traces. `ChangeOf` compares each probe's last sampled
  directional lights and open sky-ray groups with the new capture. Small changes
  within the authored angular and radiance grid can wait for their cell phase
  within the level's age bound. An angular change spanning more than one cell
  at the probe's recorded reach makes it eligible under the existing cadence.
  This bounds input displacement. Check shadow crossings on the moving-day
  route. The GPU receives only cells with light, geometry or publication work.
  Under overload the lighting ages. Each cycle's start records the window's age (median and oldest,
  `world.budget` and `Describe`); a level past its scaled age bound counts
  `behind` and prints `[sdf.mesh-gi] behind` (at most every ten seconds) with
  that level, its bound and the relit and needed rates. A re-traced probe keeps drawing its previous
  measurement until its trace lands. Clear the CPU cache and staging volume
  only when the layout changes. On a window move, publish its new coordinates and copy each completed slot. A wrong cell contributes no weight. The gather tries coarser measured corners for the missing share. A camera cut clears the previous view’s sample so its authored sky can light the first frame until a destination sample arrives. The volume
  measures at every tier: Off measures the Medium layout and applies none of its
  light (`SdfFrameBlock`'s `indirectApply` intensity zero, which also brings in
  the authored fill), while its probes keep occluding the traced lights, the
  reflected sky and, with no cascade, the sun. Without the volume nothing occludes
  any of those indoors. A surface no
  published probe answers (`sdfMeshAnswers` in `shade/sdf-light.hlsli`: every
  surface before the first publication, and surfaces past every published probe
  after a camera cut until the moved windows land) is lit by the volume's camera
  sample as one probe. Its diffuse light is the sample's
  six-axis RGB light (`meterLight`, `SdfViewExposures.LightOf`: the radiance and
  sky-light cubes summed, its open rays carrying the sky's own radiance as a
  probe's do) read about the normal by the probe cube's rule (`sdfMeshCubeFace`);
  its reflection is the environment over the share it sees open (`airLight`)
  and the mean luminance of its six axes (grey) over the rest; its traced
  lights go unoccluded. No diffuse reader multiplies a share by the sky's SH, so a cold room reads as the
  sample measured it, never white and blue-washed under the unoccluded sky. `world.indirect high` (or back to medium) resets the layout,
  which reproduces the unpublished state on a warm boot. Before the sample's first reading `meterLight` reads W zero
  and `airLight` one, so the first frames of a boot still read the open sky.
  Only pixel passes read it; a relight never does. `world.probe` answers `unsettled` only while geometry is owed (a scene
  build, a trace, a refill, a traced probe not yet published); a relight in
  progress reads as `relighting=1` on its first line.
- A frame requesting `SdfFrame.ConvergesLighting` (`Drain`) starts bounce receivers from no bounce. It keeps an independent probe whose inputs still match exactly. Each later pass relights the bounce receivers from the preceding pass until a whole pass
  moves nothing past the bound or `MaxSweeps` passes, whenever its geometry, lighting, windows or layout
  differ from the last drain or asynchronous work relit since. Its light is a
  function of those alone, never of bounce asynchronous frames left; the law
  `AConvergedLightingFrameRendersTheWindowTracedToTheEnd` compares a fresh volume's
  words with a warmed one's. The scene build, the refill and the drain run on
  the pool, and the frame waits for each through the wait door (`HostWaits`)
  under one stall deadline, which the host loop's pump allowance clips to a
  slice: a frame whose work outlasts it returns `Settling`, its residency
  answers waiting with `SdfMeshIrradiance.Convergence` (the stage, and the
  drain's pass and probes), and the loop holds the tick. A GPU trace's worker is
  never waited for, since its jobs advance only as the frame pumps the
  residency's GPU work. A drain stops at its next batch once anything in
  `DrainKey` changes (`DrainStands`) and records nothing drained; the next
  drain's first pass relights from no bounce, so the stopped one leaves nothing
  in its light (`AConvergedLightingFrameDrainsAcrossIterationsAndDiscardsAPassWhoseLightingChanged`).
  A faulted scene build keeps the volume `Settling` and fails the next frame
  that resolves a scene (`RefreshScene`), as a faulted worker or meter fails
  `Stage`.
- A record is `SdfMeshIrradianceProbe.ProbeWords` words: the key, sky shares,
  radiance cube, light bits, origin and sky-light cube before
  `SdfMeshIrradianceProbe.DepthWord`, then the packed first-hit surface words and
  packed normal-gradient words; `world.budget` and `world.probe` print the
  table's bytes per tier. The GPU runtime releases the CPU hit array once the batch is relit, keeping
  depth/sky and diagnostic lighting (`ProbeBlock` and `LightBlock`); the CPU
  reference keeps the full hits too. `world.budget` derives the retained block
  cost from those types. A level's cache holds its window grown by the
  window's band (`MarginOf`, dims/8 a side) on every side: when the window moves,
  `ProbeCache.Retain` publishes a compacted table of the cells inside that box once
  the cache holds more probes than the box has cells (at Medium 92,800 probes over
  the three levels). `world.residency`'s `probe-cache-*` line reads it. A batch's
  depth/sky and light blocks stay alive while any kept probe names them, so
  bytes per kept probe can exceed their nominal payload.
  The cache uses table-owned publication arenas, with no publication object per
  key. Retired values clear when unheld, on retirement or the next write or
  accounting visit after a held reader leaves; factory-created image buffers
  retain their images. The cache byte reading includes current table/arena
  machinery, every held retired value's blocks, and object/array headers. A
  replaced table belongs only to readers already using it and stays valid
  until those readers finish; it is outside the current cache-owned reading.
  The published table (`SdfWorldTables.PublishMeshIrradiance`) is copied on the
  device from the feedback table; no frame uploads it from the host. It fits
  the published volume exactly, is cleared before its first copies, retires
  through the frame ring and increments the binding revision when replaced;
  until the volume first publishes into a residency's tables the World set
  binds the dummy buffer and the parameters are disabled. A moved window publishes each completed slot. A device reattach brings
  new tables with no table: nothing publishes until a completed relight carries
  the volume's full snapshot into the new feedback, then every slot republishes
  at once (`RepublishAll`).
  The GPU feedback table and the published table are distinct: a relight reads
  completed prior batches, while views read the slots published for their current window.
  Feedback has a CPU shadow for reset snapshots; hierarchy staging streams
  from the scene arrays with only a root-word shadow. Upload buffers shrink
  after small flushes. `world.residency` reports scene, hit-cache and feedback
  device/upload/shadow bytes separately. `trace-scene-cpu-array-bytes` counts
  actual hierarchy array payload, including retained geometry, excluding
  dictionaries, shared bake meshes and temporary build workspace.
  `world.probe` reports publication and CPU-volume bytes. These logical holdings
  overlap process/account/backend readings; never add those readings together.
  Publication copies changed slots only, coalesced into runs.
- Each published probe contains its own measured cubes, exactly as the CPU bounce
  read sees them. Sky, surface radiance and the surface map come from the same
  hits, so an opening cannot count as sky in one sample set and a bounced hit in
  another. Every probe uses the same octahedral texel directions, weighted by
  each texel's solid angle, at both tiers; cell-specific random rotations
  stamped spatial noise into homogeneous lighting. Sharing directions
  correlates sampling error without borrowing any neighbour's light. Camera
  samples use the same quadrature. Placement uses shared short rejection rays bounded to one spacing, never lighting reach.
- A probe stands in the open (`SdfMeshIrradiance.PlaceBatch`). A centre inside geometry
  or within `Clearance` (0.1 m) first tries the nearest surface's clear exit, then
  the cell's quarter-spacing lattice nearest-first. Every candidate must stand
  clear of all surfaces and pass the back-face validity test; a short 32-ray
  local rejection precedes a full radiance trace. The former openness score is
  deleted: it moved a probe one metre off a 10 cm slab, and neighbouring floor
  cells could choose different storeys. Increasing clearance did not fix the
  sparse-curve shadow. The thin-slab witness takes the nearest safe exit (0.175 m
  at Medium), rather than the openness winner.
  Later sweeps keep the first origin. Offset XYZ rides the record and every
  gather/meter read uses the relocated origin; trilinear share stays the cell's.
  A cell no surface reaches within its half diagonal is wholly inside or outside
  and tries no candidates. A cell no candidate frees remains invalid at its
  centre; the shader rejects its invalid flag. Narrow enclosures without any
  valid lattice centre meter by camera trace. The placement and thin-slab CPU
  witnesses cover face, pillar, buried and nearest-clear cases.
- Angular surface support and the radiance cubes are sampled spatial support, not
  exact receiver visibility. Inspect corners and openings with
  `world.debug-view indirect`, separately from `ao` and `shadow`, and compare
  final shading and `world.exposure`. Check an outdoor view and move across
  the volume boundary as well as examining stills inside it.

`SdfMeshIrradianceLawTests` holds the live two-room/slab trace scene. A law makes
its volumes through `Volume()`, which disposes them when the law ends: a volume
subscribes to the shared memory account's trim event until `Dispose`, which
otherwise keeps every law's traced probes alive (the class reached 9 GB; disposed,
it peaks near 1.5 GB). The old
indirect canaries and comparison workloads under `experimental/` describe a
retired renderer and are not live verification scenes.

## Debug-world corner and boundary checks

Use a fixed camera for comparisons so chase collision cannot change the view.
Each row gives `body.pose` arguments, then `view.override camera look` arguments
(eye and target). Capture settled `indirect` and `off` views at each location.

| Location | Body pose | Camera look |
|---|---|---|
| Outer hall wall | `7.01 0.02 -5.35 307 0 0` | `4.6517 1.759 -3.5533 7.01 1.3 -5.35` |
| Along the hall | `17.33 0.07 24.30 271 0 0` | `14.3657 1.759 24.3516 17.33 1.3 24.30` |
| Teal room corner | `4.60 0.07 29.76 152 0 0` | `5.929 2.188 27.222 4.60 1.3 29.76` |
| Outdoor control | `-8 0.07 -10 225 0 0` | `-11 3 -13 -3 1 -5` |

For exposure, turn `gallery.lights.all on` and inspect the lift after
`gallery.lift 0` and `body.pose 16 0.1 38 0 0 0`. A fixed interior eye clear of
the avatar is `view.override camera pose 16 2.3 37 180 10`; the hanging
PRIMITIVES sign is visible from `view.override camera pose 18 2.8 16 270 0`.
Read the primary view's meter after the scene and lighting settle, and during
changes: an initial `meter=none` alone cannot establish that a settled room has
no visible probe. Keep the authored exposure bounds and world headroom intact.

A cold Vulkan boot shows a near-black shaft with no meter until the static draws
are ready and the three-sweep GI completes; capture only after that, and
compare Vulkan with Direct3D on the same source state with all geometry settled
([open items](../../../../docs/plans/open-items.md#vulkan-regressions-and-gpu-robustness)
records the remaining shaft difference).

The runtime trace and relight run on the GPU. To
time them, pose the teal corner (`world.lockstep on`, `body.pose 4.60 0.07 29.76
152 0 0`, `view.override camera look 5.929 2.188 27.222 4.60 4.2 29.76`), warm
once, then switch `world.indirect high`, `world.wait 5`, `world.indirect
medium`, `world.wait 5` and read the two `[sdf.mesh-gi] done … seconds=` lines.
Read `gpu-rays`, `gpu-trace-nanoseconds`, `gpu-relight-nanoseconds`, selection
and meter counters beside the main residency's done lines. Trace timestamps
include upload and readback; the ray count includes placement trial rounds.
Compare deltas over a matching workload, not startup totals from different
camera histories. Repeat on a quiet machine; a reading beside other CPU work
is not a backend speed comparison. GPU execution time alone does not establish
the full trace/relight wall cost or the lockstep frame target.

Read `world.exposure` in the hall. Double the outer-wall camera's distance,
and move the hall camera and target 8 m along +X, to check that moving the
toroidal volume creates no rectangular wall patch or bright distance band.
The teal corner must also stay closed high up where its walls meet the roof;
checking only the lower stepped strip misses the diagonal-probe case.
Aim the same eye at `4.60 4.2 29.76` to inspect that junction: a triangular
bright patch there, in both indirect and final shading, is the probe above the
roof admitted through the rays that graze past the roof's edge, which depth visibility must close. Do not infer a clean roof from the lower reference view.

## Lighting-switch convergence checks

How fast the main volume catches up with a lighting change is read from probe
ages, not from stills. Boot `worlds/debug` windowed, and once
`world.wait bakes` settles hold the day at noon
(`world.row.set state day advance {"perSecondNumerator":0,"perSecondDenominator":1}`,
`world.state.cell.set day $value 0.5`) and pose body 0 at `0 0.02 -10`. Wait
for the main volume's `[sdf.mesh-gi] done` line (its `triangles=` runs to
hundreds of millions) and note its `seconds`. Then:

- **A switch over a settled window.** Set `day` to 0.9, then 0.5, reading
  `world.probe 0 0.05 -12 0 1 0`'s `lighting-version`, `relit` and each
  level's `age-p50` and `age-max` every 60 ticks. The version moves on the
  first read; the ages say when each level caught up.
- **A switch during a refill.** Pose the body at `spawn:auction`, wait 600
  ticks, then in one script pose it at `16 0.05 -24`, set `day` to 0.9 and read
  `world.probe 16 0.1 -26 0 1 0` the same way. This is the case where stale
  relights compete with the new window's traces (`SdfMeshIrradiance.Work`).

Read the main residency's `trace-jobs=[…]` in `world.residency` beside the
ages: origins a trace job (units over jobs) show whether placement trials share
rounds. Ages count wall seconds, so a loaded machine slows them; compare two
builds in back-to-back runs with the same script.

## Gallery isolation checks

Turn `gallery.lights.all on` and leave the blinds down. Additional fixed
`view.override camera look` poses are:

| Exhibit | Body pose | Camera look |
|---|---|---|
| SPHERE, level 0 | `18 0.07 15 0 0 0` | `23 2.4 14 23 1.1 16` |
| REVOLVED, level 0 | `18 0.07 31 0 0 0` | `30.8 2.4 30 30.8 1.1 34` |
| SPIN roof junction, level 3 | `18 13.57 18 0 0 0` | `23 15.5 16.5 23 17.7 21` |
| COAT, level 2 | `18 9.07 22 0 0 0` | `25.6 11.2 23 25.6 10.3 25` |

The SPHERE (`finding-sphere-step`) must shade continuously across its front,
without a split or patch from the plinth or hanging sign. The floor is shadowed in
`shadow`; do not attribute an indirect-view line to sun cascades. Angular surfaces remain sampled support; a receiver all depth tests reject has
no measured light.
The SPIN dotted ceiling seam reproduces in
beauty but not in `indirect`, `normals` or `shadow`
([open items](../../../../docs/plans/open-items.md#lighting-and-gi)
records the experiments).

COAT's authored `specular: 0.35` is dielectric F0, not coat strength: it
reflects a substantial neutral environment over its red diffuse albedo.
`coat` currently adds a direct-light lobe in `sdfMaterialSpecular`; it is not
read by the environment-reflection branch in `sdf-light-stage.hlsli`. Compare
the material with coat disabled separately from changing its base F0 before
attributing a pale colour to the coat layer: coat zero leaves the salmon colour,
while coat 0.5 with base F0 reduced from 0.35 to 0.04 restores a saturated red.

See the [handbook](../../../../docs/rendering/sdf/handbook/lighting-and-shading.md#the-mesh-paths-irradiance-volume)
for the lighting model and [verification](../../verification/SKILL.md) for GPU
leases and named, device-free World runs.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall