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-bake.md

View on GitHub
# The mesh bake: contouring, groups, store and audit

Read this before changing the bake (`SdfMeshPathBake`, `SdfSampledLattice`,
`SdfDualContouring`, `SdfMeshBakeGroup`, `SdfMeshGeometryBuilder`, the mesh
region or the mesh store), or when a baked mesh looks wrong. Back to
[../SKILL.md](../SKILL.md). [Frame rendering](../../../../docs/rendering/sdf/handbook/frame-rendering.md#the-bake)
explains the technique.

Every view renders a residency's program from meshes the program is baked into,
with no field walk in the frame. The bake samples the field on the GPU through
the interpreter, contours the samples on the CPU, and stores the meshes.

## Reproducing a cold bake

Use `puck_world_start` with a fresh `cacheDir`, `paused: true` and
`lockstep: true`, then `world.wait bakes` and `puck_world_stop`, one World at a
time. `paused` stops authority ticks; it does not stop animated placements on
the display clock. `lockstep` pins that clock before the first frame too
(`WorldFramePresenter.CaptureFrame`), so the first bake captures the same poses.
Pausing or enabling lockstep after attachment is too late to control those
initial inputs. Keep the backend and built source state fixed across repeats.

Two things a fresh `cacheDir` does not reset, and one lockstep hides
([the wall-time measurement](../../../../docs/plans/field-programs/research-bake-time.md)).
The driver's own shader cache decides the opening wait: the bake's GPU client is
created with the residency's tables (`SdfWorldResidency.EnsureTables`), after
every one of its pipelines compiles, so a build whose shaders the driver has
not seen waits 15 to 35 seconds before its first lattice and a repeat waits
under one. Lockstep and held frames drive background work without the GPU
budget (`SdfGpuWorkBudget.Observe`), so a lockstep bake measures the worker
pool's pace and a free-running one the budget's, which was three times slower
when the frame's GPU time passed its period. To trace a bake from process
start, set `DOTNET_EnableEventPipe` with an output path and provider config in
the World's environment rather than attaching after the start; the runtime's
allocation events (verbose level) slow allocation-heavy stages, so time a bake
without them.

For timing, `bench startup --bake` pins those clocks with `--paused --lockstep`.
Lighting convergence can delay the readiness barrier after the bakes finish;
allow for it in `--timeout-seconds`. Its per-sample `timeline.log` keeps
the observed timestamp and stream of every stage/job line. Read those spans beside
a sampled thread-time trace; the `cpu` stage totals are summed worker elapsed time,
including waits and suspension, not processor time. With a worker per logical
processor sharing cores they overstate what a stage costs alone, and they swing with
whatever else runs. Attach `dotnet-trace collect -p <World pid> --profile
dotnet-sampled-thread-time` during the bake and count only `CPU_TIME` leaves: it
splits the World's processor time across stages and the work beside the bake (the
desktop capture's readback scaling, the frame). A CPU change to `Land` is measured
load-independently by replaying the group meshes `Land` receives through
`SdfMeshChunks` on one thread and counting that thread's cycles
(`QueryThreadCycleTime`); hash every level's indices and errors to show an
equal-output change changed nothing.

Compare the key sets before comparing each key's decompressed payload. A
different pose can legitimately produce a different key. The store codec maps
material ids to canonical places before writing every chunk and level, so a
program's palette registration order cannot change a keyed payload. The library
maps those places into the loading program's palette. Ids outside the group's
palette retain their values and are reserved before canonical ids are chosen,
so they cannot collide with a place. Trace a varying key back through `SdfMeshBakeGroup` and its saved poses,
and use `puck mesh audit --cpu --group ...` to separate CPU contour work from
device sampling. Do not infer a GPU race from a whole-store hash alone.

## Contouring

- **Count ownership classes, then fill owned indexes.** `SdfSampledLattice.Refine`
  counts distinct samples by the cell faces they touch: low boundary, interior,
  or high boundary on each axis. Every interior coordinate has the same holders,
  so its class contributes `split - 1` samples per interior axis. The selected
  count admits cells. `FineKeys` numbers their slots in the original cell/sample
  order, then sizes the key buffer from its own count and fills it through those
  slots. Every sample buffer takes that key buffer's length, independently of
  admission's estimate, without growing managed lists and copying them.
  Preserve that order and the region admission order: both feed the bake.
- **Collapse line samples have one owner.** `SdfMeshCollapse.Collapser.AppendLine` links
  samples by index and retains each edge's append order when a collapse moves
  them. `MeasureLines` must finish before `CommitLines` relinks any sample.
  This is the line counterpart of the collapse's existing surface-sample links;
  changing traversal order can change equal-distance choices.
- **Reuse crossed topology.** `CrossingEdges` saves each crossed fine cell's
  low corner and mask after `CloseSheets`; gradient requests and
  `SdfDualContouring.ExtractRefined` consume that same coarse-cell/fine-cell order.
  Fine signs cannot change between that preparation and contouring. Coarse
  vertices remain interleaved in their original order; appending all fine
  vertices afterward changes the payload.
  Adjacent fine cells in an X row reuse their common face's four sign bits. The
  row reads its first face, then one new face per cell, after `CloseSheets` has
  fixed every sign; it retains the original cell and edge enumeration order.
- **Index a collapse fan once.** `Collapser.Kind` indexes outgoing edges and
  pairs each with exactly one incoming edge before walking their permutation.
  `OneRing` must visit every triangle and return to its start: several disjoint
  cycles are not a manifold fan. The index is scratch for that invocation, with
  every endpoint it can read cleared before filling, never a cache across collapses.
  Keep feature penalties in edge order, including the prefix before a malformed
  edge locks the fan: a locked place can still be another collapse's target,
  whose cost reads those quadrics.
- **Reuse a collapse's source fan until commit.** `SdfMeshCollapse.Collapser.PrepareFrom`
  lays out the unchanged source triangles once for all attempted neighbours.
  A refused neighbour mutates no source geometry; the first accepted neighbour
  ends that fan's attempts. Its reverse edge witnesses share that lifetime:
  a midpoint's nearest old surface and inherited error depend only on its two
  places, material and the prepared fan. `PrepareFrom` clears the witness map,
  and `Pass` stops at its first commit; never retain those answers across it.
  `MeasureReverse` computes a maximum of point errors: once a point has a
  witness no farther than the maximum established by preceding points, a nearer
  witness cannot change the result. The cached distance is an upper bound plus
  the next old triangle to visit, not necessarily the exact nearest distance.
  A tighter later target resumes that search; only a completed search may raise
  the maximum. Shared edge midpoints precede the unshared centroid.
  Forward checks measure the removed vertex's samples first, then every other
  tracked sample. An original vertex retained by its tracked triangle witnesses
  its own position, normal and material exactly; the other samples choose their
  nearest admissible witness. Ordering avoids later work when an early sample
  refuses the collapse. A nearest point already beyond the current distance
  limit needs no interpolated-normal calculation.
- **Retry refused edges only after their inputs change.** `Collapser.Pass` keys
  each rejection by its directed edge and the revisions of what the refusal read
  (`Collapser.Outcome`): the collapsing place's fan always, the neighbour's fan
  only for a link refusal, and the level's budget only for a measured one, so a
  shape or link refusal stands into the next level. Every other check reads the
  place's own fan, its tracked and line samples and the neighbour's fixed
  position; a new check that reads the neighbour's fan returns `RefusedLinks`.
  `Commit` is the one mutation door for topology, surface and line samples, and
  inherited bounds; it stamps every endpoint of the old fan, including deleted
  triangles. The cache only skips failed attempts; every accepted collapse still
  passes all checks. `PrepareFrom` lays out each source fan's corners, link
  stamps and geometry once for every neighbour tried; its tracked samples and
  lines are listed by the first neighbour that needs them. A `Dictionary<long, …>`
  keyed by two packed places takes `PackedIntPairComparer.Instance`: long's own hash folds the halves,
  and neighbouring places collided until the refusal lookups dominated a mesh.
  A faster query or a different witness assignment still needs the field audit:
  tiny arithmetic and ownership changes can alter later collapse choices and
  uncover surface that the sample-to-mesh bounds alone do not detect.
- **One contouring.** `SdfSampledLattice` contours a GPU-sampled lattice through
  `SdfDualContouring` over `ISdfContourLattice`; never write a second mesher.
  A final lattice refines the cells its samples cannot resolve
  (`SdfSampledLattice.Refine`: sheets or gaps thinner than a cell, not a solid's
  edge or crease a line crosses near its tip, outside corners of different
  materials, two patches in one cell) and contours them at the fine spacing
  through `SdfDualContouring.ExtractRefined`; the cells touching them contour
  fine from interpolated coarse values and merge each piece into one vertex,
  which keeps the mesh crack-free. Never refine a cell without that ring: a
  whole cell next to measured fine samples cracks (`SdfSampledLatticeLawTests`).
  A thin sheet's cells take a finer split where the ordinary one leaves room
  (`SdfMeshPathBake.ThinSplit`), and so does every measured cell sharing a face
  or an edge with one: a sheet runs past the last coarse line that caught it,
  and a coarser stride beside it steps over the sheet between the fine samples
  the two cells share, ending it in a cap inside the solid whose merged vertex
  sits between the sheet's faces (the range windows' rims).
  The ring's crossings carry interpolated coarse gradients, so a crease inside
  it is cut: a gap between two inside samples refines only where the falls meet
  half a fine cell below the surface. Solids that touch (a stair's treads, a
  board on its table) meet at the surface, and refining that seam chamfered the
  concave crease above it by a cell.
- **Touching solids are one solid to the contour.** A Box is sharp unless its
  document rounds it ([decision](../../../../docs/decisions/engine-design.md#a-box-is-sharp-unless-its-document-rounds-it)),
  so boxes that touch meet with no groove at the seam and no crevice where the
  seam meets a third face. Inside a union the field is the distance to the
  nearest face of the solid a sample lies in, which beside a seam is the shared
  face, so a value and gradient there measure to the seam, not the surface. A
  transition ring's crossing is therefore searched along its edge as a measured
  one is (below), and the field correction moves no vertex along a gradient its
  own triangles face away from (below). The interpolated normal (`TryNormal`)
  still reads such gradients at a seam, which shades a cell-wide band beside a
  concave crease where a layer thinner than the cell meets its neighbour (the
  strips under `hall-floor-3`). Rewriting sub-cell gap samples as inside, or
  leaving seam-pointing corners out of the interpolated normal, opens holes
  (open edges) across the debug world's store-wide audit wherever it helps a
  seam, so the contour does neither: a seam's residue is fixed in the shape
  language (sharp boxes) or the lattice, not patched in the contour.
  Refining every cell instead (5 mm across the Moth) bakes about 8 M triangles
  in 20 s. The fine-sample budget (`MaxFineSamples`) measures the cells the
  samples cannot resolve first, then each detail region's cells, the region
  covering the fewest cells first, leaving a region that would carry the count
  past the budget to the coarse contour, and takes the finest split serving the
  most regions, down to two fine cells a coarse cell: a member whose region
  spans a whole union (a slab's 2 cm ceiling finish) costs as much as every
  other member together, and dropping every region for it left the strips
  under the slab at the coarse cell, drawn or lost by where the coarse samples
  fell. A sheet thinner than the coarse cell survives any refinement and none
  of the coarse contour.
- **Crossings stay on their lattice edges.** Before measuring crossing normals,
  `SdfSampledLattice.CrossingPoints` and `AnswerCrossings` bracket each zero along
  its sign-changing edge through the bake's existing point batches. Both the
  contour and its gradient requests use that root. Projecting a linear estimate
  along its nearest normal can land on another face of a corner, supplying the
  wrong tangent plane and serrating the rim. A transition ring's edge is
  searched too, bracketed by the signs its interpolated ends give the contour's
  topology: inside a union the interpolated value is no distance (a 2 cm layer
  under a 6 cm coarse cell measures to the face it shares with its neighbour),
  and its linear estimate put a slab's underside a centimetre up inside the
  slab. The field along such an edge need not change sign where the
  interpolated end says it does (a coarse cell's corners interpolate the two
  wedges of an XOR's pinch as one solid), and the search then ends against
  that end, off the surface: a crossing whose bracket still ends at an
  interpolated value (`CrossingRoot.Bracketed`) and whose field there does not
  read zero gives no plane (`Lattice.TryCrossingNormal`). Its measured
  gradient is the nearer face's, and a plane through the lattice point along it
  stands up to a fine cell off that face and keeps a merged piece's planes from
  meeting at its crease. Only samples displaced by `CloseSheets` keep their lattice
  interpolation: their intentional surface differs from the original field.
  The search (`CrossingRoot`) measures two trials a round, a tolerance apart
  about an estimate (the linear one, then the secant through the last round's
  pair), so a root the estimate all but hits closes the bracket that round, and
  cuts the bracket in thirds once the thirdings it still needs fill its
  remaining rounds; it ends once the bracket is an 8,192th of the edge wide (the
  root, its middle, within a 16,384th), in at most eleven rounds. The
  `ACrossingLandsWithinASixteenThousandthOfItsEdgeInAFewRounds` law holds the
  bound and the cost. Each round is a readback round trip of the group, and
  only the groups the memory account admits hold a final lattice, so a group's rounds bound its
  latency: a search must not trade fewer samples for more rounds than its worst
  root needs (a one-trial secant search's worst roots took up to 37).
- **Signs are read once.** `SdfSampledLattice.FineInside` keeps each fine
  sample's sign in a bit once read (`AnswerRefinement` clears them,
  `CloseSample` keeps a closed sample's), and the contour's corner masks,
  `CrossingEdges`, `GradientPoints` and `CloseSheets`' line scans and face tests
  read signs through it; a value is computed only where its magnitude is used.
- **Features are placed and shaded as features.** A vertex whose crossings'
  planes all meet and turn by over 30 degrees is a feature: it lies on the
  crease, inside its cell (a point past the cell folds the quads around it into
  teeth along the edge). A convex crease up to half a cell past its cell is
  handed to the neighbour that holds it (`SdfDualContouring.HandOff`), whose
  vertex moves onto it; clamped instead, a diagonal or curved crease loses its
  vertices in a row of notches. The cell that hands it over keeps its vertex on
  its crossings' side of the crease (`BesideCrease`), or the quads it shares
  with the crease vertex fold. A feature takes its crossings' normals, each quad
  splits along the diagonal that faces out as its lattice edge says (next
  bullet) and, where both do, the one that turns least from its non-crease
  corners' normals, chosen again after the final field correction moves
  vertices, and
  `SdfContour.SplitAtCreases` splits it per side at 25 degrees. Incident faces
  identify shading creases independently of the placement's feature flag:
  correcting a vertex must not erase its sharp edge. A lifted chamfer's corner
  meets its neighboring bevel at only 31.4 degrees, so a 32-degree threshold
  blends that corner into a jagged band. Every vertex no crossing pins
  to the surface (`SdfContour.Solved`) is checked against the field before the
  split and moved toward the surface where a rounding near the cell's size left
  it proud. `SdfMeshPathBake.ContourProjection` bounds that movement before any
  incident triangle reverses its original facing; an incomplete move keeps its
  original normal and feature flag. One the contour kept beside a sharp convex crease (`SdfContour.Beside`)
  that lies inside the solid stays a crease vertex when moved, or its face's
  normal shades the other face's quads beside the edge. A gradient shorter than
  a tenth of the field's typical slope straddles a crease and moves nothing
  (`SdfMeshPathBake.KinkGradient`): value over length is no distance there.
  Nor does one whose gradient turns away from the way its own triangles face
  (`ContourProjection.Outward`): inside a layer thinner than a cell the
  gradient points at the seam the layer shares with its neighbour, and the move
  lifted the vertex onto that seam.
- **A contour holds the facing its lattice gave it.** A dual contour's
  connectivity is the lattice's signs alone: one quad per sign-changing lattice
  edge, joining the four cells around it, and that edge runs from inside the
  solid to outside. Its direction is each quad's facing with no estimate in it
  (`SdfContour.QuadAxes`), and `SdfContourFacing` is the one place a triangle is
  judged against it: a triangle faces out when its area normal has a positive
  component along its quad's edge, and one lying within fifteen degrees of
  edge-on to that edge (a quad squashed into a face that passes through the
  edge) is judged by its corners' patches, the sum of each cell patch's own
  sign-changing edge directions (`SdfContour.Patches`,
  `SdfContourFacing.Patch`). Vertex normals and a triangle's own earlier facing
  are estimates a misplaced vertex has already turned, so no stage orients by
  them first. Four things hold a contour to it:
  - *Placement keeps a vertex in the region its quads allow*
    (`SdfDualContouring.Within`). The four cells around an edge lie in the four
    quadrants about its line, and a quad faces out while each vertex keeps to
    its own quadrant, so an edge bounds its cells' vertices only along the two
    axes it does not run along. A vertex may therefore reach a feature past its
    cell (`FeatureReach`) only through a face its patch does not cross; past a
    crossed face it lies among the cells its own quads join it to and turns
    them over, so it clamps instead. A vertex no feature pins also keeps
    `CrossedClear` of a cell clear of the faces its patch crosses (`Clear`): on
    such a face the quad it shares with the cell across it has no width, and
    which way its triangles turn is rounding.
  - *The settle* (`SdfDualContouring.Settle`, after the hand-off and the merge)
    finds every quad neither of whose splits faces out and returns the vertex
    whose return fixes it, or all of them, to its crossings' mean, which lies in
    its own cell. A merged piece's vertex stands for several cells and has no
    region of its own, so the settle is all that holds a transition fan. A
    piece whose vertex the settle returns and whose planes meet along a crease
    past its block (the faces of a wedge whose edge the neighbouring measured
    cells hold) has no point on both faces, and its returned vertex lies inside
    the solid, where the field check moves it onto one face and turns the other
    face's triangles against the field; the merge runs again with each such
    piece split into one piece per face (`SdfDualContouring.SplitAtCreases`).
    A piece the settle leaves alone keeps its one vertex: splitting every
    creased piece, or every piece holding two opposite sheets, turns more
    triangles on the XOR and the range windows than it fixes.
  - *The split* (`SdfSampledLattice.SelectDiagonals`) takes the diagonal whose
    triangles face out where only one's do, before any normal is read. Two
    quads that hold one pair of vertices as opposite corners (a merged vertex
    stands for several cells) would both split along that pair, an edge four
    triangles hold; the later quad takes its other diagonal.
  - *The field check's moves* (`ContourProjection.Move`) are clipped before a
    triangle that faces out stops doing so, beside the clip against its
    original facing.
  To measure a change here, count a contour's quads with no split that faces
  out (`SdfContourFacing.Splits`) after the settle, where a contour without
  merged pieces has none, and again after the field check. What this does not
  hold: a triangle can face out by every lattice fact and still be turned past
  a right angle from the field's gradient. The audit's remaining flips are of
  that kind: a sliver between two rows of vertices a few hundredths of a cell
  apart along a crease, a web across a junction of two creases, a vertex its
  planes put off the surface where the field check refuses to move it, and a
  face narrower than a cell between two creases (the Moth's shin blades). They
  are [open](../../../../docs/plans/open-items.md#bake-detail).
- **Vertices a cell cannot tell apart are one vertex.** Once the field check has
  moved its vertices, a contour is finished in one place, `SdfContour.Finished`,
  which both the bake's split and `ContourLevel` call: it welds every quad edge
  shorter than `WeldCells` of the finest cell (`SdfContour.Weld`), shortest first,
  then selects diagonals and splits creases. A row of cells beside a crease puts
  its vertices a few hundredths of a cell off the crease's own row, and several
  cells crowd the point where two creases meet; the strip or web between them is
  slivers whose facing is rounding. The crease's vertex (`Features` and not
  `Beside`) keeps its place and takes the other. A weld is refused where it would
  join a quad's opposite corners, break the link condition (a neighbour the two
  share that no triangle between them holds), leave a quad that faced out along
  its lattice edge with no split that does, or turn a surviving quad by more than
  `WeldTurnCosine` (a small quad beside the move folds against its neighbours,
  as on a closed sheet's rim). A quad the weld closes becomes a triangle or goes.
- **A crossing's gradient within a tap of a crease is a blend of the faces
  meeting there**, and its tangent plane is neither face's. A lattice plane that
  falls within a few tenths of a millimetre of a flat face (the narrowed box
  puts one there) reads such planes at every crossing along the rims on that
  face, and the cell's least-squares point is drawn to the face it shares with
  its neighbour. Read `puck mesh audit --cpu`'s clusters by where the lattice
  planes fall before blaming the shape.
- **The bake's field is no true distance.** Scopes, flares and non-uniform
  scales read well under the distance (a fifth of it on the Moth's shins). A
  value becomes a distance only over the gradient's magnitude (the bake kernel
  writes the gradient in field units per world unit), and a test of how a value
  changes over a step is measured against the field's own slope there, never
  against the step's length (`SdfSampledLattice.PassesBetween`).
- **Sheets thinner than the fine cell are closed before they contour**
  (`SdfSampledLattice.CloseSheets`): left to their samples they hole, fray into
  slivers where they thin, and their two faces cross. An acute wedge reads as a
  sheet along a line near its tip; a line a few fine steps beside it inside for
  two steps tells it apart (`Thickens`), or its rim closes into lumps. Only
  features and single-face cells read crossing normals: elsewhere (a fillet
  under the cell) they smudge flat faces, so other vertices keep the
  interpolated gradients. Such a vertex on a fillet under the cell carries the
  fillet's normal, so `SdfContour.SplitAtCreases` gives the corners of its quads
  that face more than 25 degrees from that normal a copy with their face's
  normal (a plinth's authored 6 mm fillet at 21 mm cells otherwise shades a
  band a cell wide along every edge). The material cut samples and searches by
  place, not by copy (`SdfMeshMaterialCut`), so the pieces either side of a
  split edge meet at one boundary point.

## Groups, poses and materials

The dispatch's fixed `MeshBakeMaxSamples` budget counts sampled values, not
the saved pose rows appended to its input point table. Each slot of the
background GPU work holds its batch's point table, a host-visible buffer the
kernel reads in place (`SdfMeshBakeGpuWork`), which the service owns and
reserves (`SdfGpuWorkRecording.HostBuffer`), grown in 4 MiB granules once the
slot's last job is released (`SdfGpuWork.Granule`), and bound through the slot's
own World set at the bake's point member, where the tables' World sets bind the
unused-member buffer (`SdfWorldTables.BackgroundWorldSet`).
`SdfMeshBakeBatch.InputRows` is the highest input prefix actually read: explicit
points retain their sample offsets; saved poses still begin after all samples.
A grid-only batch without poses needs no input rows. Do not allocate or write
its sample-count holes; nothing reserves `MeshBakeMaxSamples` rows merely
because that is the sampled output budget. Interior holes before explicit
points or poses remain part of the current kernel layout. Preserve their
addresses when changing storage. The holes are never read, so a slot writes only
the runs the batch names (`SdfMeshBakeBatch.PointRuns`), comparing nothing.
Charging poses against the sample limit can strand the first pending lattice
forever: a nearly cubic lattice plus a sparse pose span no longer fits, so the
scheduler takes no work and every group behind it waits. Cold bakes expose this;
warm meshes bypass it. Keep the sampled-output bound while allowing the input
table to carry all the batch's poses. The posed-cube and growing-input-table
laws exercise that boundary.

- **Edge weathering reads the baked normal field.** `sdfMeshSurfaceNormal`
  supplies the visibility record's curvature through `sdfMeshMeanCurvature`:
  half the surface divergence of interpolated unit normals in world units.
  Reuse the triangle's normal reads, keep its sign independent of the camera,
  and return zero for degenerate triangles or meshes without normals. A broad
  plate and a narrow bevel must read different curvature; a constant zero
  silently disables every material's `weathering.edge`.
- **Groups are planned in one place.** `SdfMeshBakeGroup.Plan` forms a
  program's groups, geometry and pose rows; the bake and the mesh audit both
  call it, so a change to grouping changes both.
- **A group's bound stops at the frame's far distance.** The plan clamps each
  instance's bound to a cube of the far distance about the instance's centre
  (`SdfMeshBakeGroup.Clamped`), and a world that authors no `render.farDistance`
  takes `SdfFrame.DefaultFarDistance`, 40 m. A creation placed at the origin
  whose shapes stand hundreds of metres out (a valley wall sector) then bakes
  empty on every backend and in `puck mesh audit --cpu` alike, and its entry in
  the done line's `empty=[...]` says `bound clamped to the far distance`. A
  scratch world cut from the debug world keeps the debug world's
  `render.farDistance`, or its far terrain is no evidence about the bake.
- **A static copy is one group.** Its shapes bake as their union
  (`SdfInstanceRange.BakesWithPrevious`) on a cubic lattice past the per-axis
  cap with per-shape refinement regions (`SdfMeshPathBake.UnionFinal`); its
  serial contour of about a million samples is the bake's long pole on the
  debug world, so the plan lists unions first, which decides only among groups
  the demand points rank alike.
- **Work goes near-first** ([residency](../../../../docs/decisions/residency.md)).
  `SdfMeshDemand` holds the eye of every view of the residency's latest frame
  (an `Elsewhere` or hidden view demands nothing; a filmed camera measures in
  its own image's pixels, `SdfViewSnapshot.DemandHeight`; a window fitted to
  its glass measures in the display pixels the glass spans from the viewer's
  eye, `WorldWindowFrustumFit.ShownHeight`, and demands nothing of a box
  outside its frustum, `SdfViewSnapshot.DemandWithinView`). A group whose
  planned box (`Group.TakeDemandBox`, kept before `Begin` cubes it) projects
  past a pixel ranks by the pixels a metre covers at the box, nearest first
  whatever its size; one under a pixel ranks after. Ranking by projected size
  instead let far terrain and shells outrank the lobby's small parts, and the
  occupied area landed no sooner than in plan order. `TryTake` takes
  lattices in `ByRank` order of the groups the tally holds as offering a lattice
  (`GroupTally.Offered`, into two heaps), at the ranks `Prioritize` last
  measured, the work queue runs store loads and
  lattice answers ahead of its stages (`Enqueue`, urgent) and every CPU stage of
  the bake (`Schedule`), and `SdfWorldTables.OrderLanding`
  orders owed meshes for landing in that order, the plan's or the list's order among
  equals and a draw no host box bounds first. With no demand point (the CPU
  laws, `puck mesh audit --cpu`) the plan's order stands. Order never changes
  a mesh. `world.residency [radius]` reads when the groups landed and became
  resident from the bake's start, near the primary seat's eye and everywhere,
  with the store's reads, the region's landing, program build times and the
  probe cache's bytes.
- **The bake's CPU work is one process-wide pool.** `SdfMeshPathBake.Schedule`
  queues every residency's work on one pool of a worker a processor: the
  lattice answers (decoding a readback and narrowing a group) first, in arrival
  order, then the stages by group priority. A pool per residency oversubscribes
  the processors three times over on the debug world, and workers below normal
  priority lose them to the irradiance trace and the machines, more than doubling a
  cold bake. The workers are threads of the pool's own at normal priority
  (`SdfMeshPathBake.StartWorkers`), blocking on an operating-system semaphore
  while idle: held as `Task.Run` items for a whole bake, they kept the process's
  other thread-pool work (timers, `Parallel.For`, the store's account) waiting
  5 to 17 seconds while the runtime injected threads. The done line's
  `tail=` is the seconds from the last moment work was queued behind every
  worker to the bake's end: the serial tail in which the largest groups finish
  alone. A completed batch's readback is copied out by a reader of its own,
  never behind the pool (`SdfMeshBakeGpuWork.Complete`'s `Readers`, a
  `BoundedWorkQueue` of a reader a slot on the host's thread pool), and its slot
  is released as soon as the copy is taken, so neither the frame thread nor a
  worker busy contouring holds the GPU's next batch back; the reader copies a
  final lattice's slab into the lattice and queues each answer on the pool ahead
  of every queued stage, each answer reading its slice of the copy in place
  (`SdfMeshPathBake.AnsweredSamples`, shared until its last answer ends), then
  advances `Progress` (`SdfMeshPathBake.Progressed`), since a field slice's
  answer queues no work item.
- **A bake draws on the machine's headroom, not the play bar.** Its group
  workspaces, readback, store writes and sample reads are authoring owners
  (`MemoryAllowance.Authoring`), held to the machine's room alone; the meshes it
  publishes into the library are play. A player's build holds authoring to the
  play bar (`MemoryAccount.SetAuthoringOnPlayBar`), so a bake there degrades
  and never fails ([the owners and their allowances](../../../../docs/plans/streaming-and-memory.md#the-large-host-owners)).
- **A dispatch's answer never waits for host memory.** The copy, and a sample
  set read in place of a dispatch, are charged to the bake's readback owner
  inside a standing reservation of `SdfMeshPathBake.ReadbackBytes`: the take
  grants a lattice its output bytes only while they fit what is left of it, and
  takes nothing, admitting no group, until the reservation is held, so the
  groups the account admitted can always be answered (the done line's
  `stop=[readback:…]` and `host-refusals=[readback-waits:…]`). The reservation
  goes once a take finds nothing to take, or the residency is released, and no
  answer holds any of it. Elsewhere a host-memory refusal defers rather than
  fails (`SdfMeshPathBake.Refusals`): a sample set the store keeps or reads past
  the account's room is dropped or missed (`store-writes-dropped`), a copy into
  the library the account refuses (a landing's published mesh, a follower's
  renumbered take of its leader's) waits parked until its bytes can be reserved
  as play's, since the library's copy is play storage (`Park`, `copy-waits`),
  and any other refused stage starts its group's
  final lattice again under an admission of at least the most the group's
  storage held and the bytes refused (`Group.PeakFloor`, `readmitted`). A request's points are its group's
  workspace (a final lattice's one point buffer, reused round to round; the
  group's crease and material points, cut to nothing by the answer that
  finishes them), so the reader reads a lattice's request and group only while
  its ticket is `Decoding` (`SdfMeshPathBake.Receive`: the decode and the
  sample key), before the queued answer can move the group on; whatever else
  it needs of the group the take fixed in the batch (`SdfMeshBakeBatch.Poses`,
  `Keeps`). Hashing the points after the answer is queued reads a later
  round's points, or throws `ArgumentOutOfRangeException` on a buffer already
  cut. A group's lead, which paces
  admission (`SdfMeshBakeBacklog.ObserveLead`), runs from its admission to its
  first `Schedule`d stage: a sample probe and an answer are queued urgent
  (`Enqueue`), never through `Schedule`: a probe ended in the admitting take
  would measure a lead of microseconds and clamp admission to one round of the
  workers. Only the groups the process memory account admits hold a final lattice
  (admitted at its first slab, whose answer allocates the lattice's values), by
  each group's own peak (`PeakOf`); the admission rules are in
  [data and memory](../../dotnet-performance/references/data-and-memory.md#owned-storage-and-byte-admission).
  Unadmitted groups keep refining their small coarse lattices. A first slab
  handed back unanswered (`Abandon`: a job whose recording failed or whose
  service was disposed) keeps its admission;
  counting its retry as a new one let returned first slabs fill every admission
  and stall the bake. A stage the host memory account refused starts its
  group's final lattice again (`Readmit`); any other stage that throws finishes its group with no new mesh
  (`[sdf.mesh-bake] ... failed`, `Fail`), releasing its reservation and
  workspace, and a later program bakes it again. A group a later program does
  not keep, or whose residency is released, is retired (`Group.Retired`): the
  pool drops its queued work, an answer arriving for it is dropped, and its
  workspace is freed when its running job ends; `Retire` never waits.
- **Nothing array-sized runs under the bake's gate.** The frame thread takes
  `m_gate` in `PrepareFrame` and `TryTake`, so a worker fills a
  group's lattice, points and answers on its own job, which only that group's
  one running job touches, and takes the gate only to publish the group's next
  request or stage. The done line's `frame-gate=[max,total,over-1ms]` reads the
  frame thread's waits on the gate, and `gate=[site:entries/wait/hold/max]`
  every entry's wait and hold by site (`SdfMeshBakeReport.Gate`, taken through
  `EnterGate`, the one door to `m_gate`): on a cold debug-world bake the
  frame thread's entries (`frame`, `prioritize`, `retier`, `judge`, `dress`,
  `take`, `observe`, `evict`, `begin`) hold the
  gate far longer than the workers' own sections do, so the
  workers' waits are the frame thread's holds; `begin` (`Start`'s call of
  `Begin`) and `evict` (the eviction sweep, and the evictions a frame makes) run
  inside another entry's hold and are counted out of it. Whether a group still stands in
  the bake is its `Listed` flag, which only `GroupList.Set` and `Clear` move,
  never a search of the list. No entry walks the list for counts either:
  the take reads how many groups fly, run a stage, hold an admission, wait for
  their first stage or hold a lattice from `GroupTally`, which every setter of
  those states settles (`Group.Settle`, the one place a group's contribution
  moves a count or a set), and the take walks only the groups the tally holds as
  offering a lattice, the ready and the wanting an admission apart, which it
  does not read at all while the pool backlog closes admissions and does not
  start when none holds one. `ObserveResidency` walks only the groups that landed or
  were drawn again and have not stood in the mesh region
  (`Group.AwaitResidency`, the one door a group joins that set by, queued from
  any thread and taken in under the gate). A start decides whether the store
  may hold a mesh or checkpoint from its known entries
  (`SdfMeshStore.MayHold`, `MayHoldCheckpoint`, the same per-identity sets as the
  sample probe below), never a file read. A report line written while the
  thread holds a gate waits for the gate's release
  (`SdfMeshBakeReport.GateLeft`): a write to a piped standard error can block
  on its reader, and a frame thread blocked there holds every worker.
  `Prioritize` measures a share of the groups' priority and view each prepared
  frame, outside the gate but on the frame thread, from a cursor
  (`GroupSweep`, the one cursor `MeasureDemands` shares): a rank is up to a
  measure old, a restart ranks every group it plans, and a group planned in a
  listed group's place takes that group's rank (`Replace`). The counts of the
  groups that owe the frame and of those with nothing to draw
  (`CountHoles`) move with each visit and each `Replace`. The dresser reads the
  groups the bake names changed since its last read (`Touch`, taken by
  `FrameAccess`) and every group only when the list was replaced, the program or
  the copy layout moved, or a verdict declined (`TouchAll`). The groups that keep
  a floor (`m_keepers`) are the only ones the eviction sweep, the mesh region's
  naming of kept floors and the trace judge read, the judge through the groups
  whose floor, done state or product changed (`Judgeable`). The retier decision
  still reads every group once a measure.
- **A stage's scratch is rented, its result exact.** A CPU stage grows its
  per-vertex and per-quad workspace in `RentedList<T>` and leases its tables
  (`RentedArrays.Rent(minimumLength, out array)`). Arrays up to 1 MiB reuse the
  shared pool's buckets, and larger arrays of reference-free elements a bounded
  large pool (`RentedArrays`, trimmed when a bake's last group finishes and on
  `MemoryAccount.TrimCaches`), so a group's workspace is reused by the next
  group instead of left on the large object heap. The stage copies
  out only the arrays its result keeps. A group's lattices and point tables
  stay in owned native storage. A rental can be longer than requested and its
  contents are unspecified. Fill the range before reading it and track the
  logical count separately. The
  done line's `managed=[allocated,gc-pause,collections]` reads the process's
  allocation and collector pauses over the bake's window. The contour, crossing
  search, weld and crease split rent theirs; the collapse
  (`SdfMeshCollapse.Collapser`), planar merge, chunking and material cut still
  allocate theirs afresh for each mesh
  ([open](../../../../docs/plans/open-items.md#refactoring-campaign)).
- **A dispatch fills its samples.** A take takes lattices by priority until
  `MeshBakeMaxSamples`, passing over one too large for what is left and taking
  smaller ones behind it; stopping at the first that did not fit left the debug
  world's dispatches under half full.
- **One geometry bakes once a bake.** A group whose sealed geometry another
  group of the same restart already bakes or loads waits on it
  (`Group.Leader`, `Follow`) and takes the library's mesh, renumbered, when the
  leader lands; the start line's `shared=` counts the groups a restart plans that way. The
  renumbering shares immutable geometry and allocates remapped triangle materials, so it runs on the pool
  (`TakeLanded`), outside the gate the frame takes; a leader that found no
  surface lands the follower empty too (`Draw(group, null)`), or it would keep
  drawing the mesh it had before the rebake. An offline bake of chosen groups
  (`puck mesh audit --cpu --group`) names them in `SdfMeshPathBake.Selection`:
  an unselected group finishes unbaked and leads none, where answering it as
  empty space handed its empty result to a selected follower.
- **One geometry bakes once across residencies.** A group the restart's index
  does not cover starts through `SdfMeshPathBake.Start`, the one caller of
  `Begin`, which asks the library (`SdfMeshLibrary.Share`) whether a bake of its
  geometry and identity already runs in any residency holding the library. If
  one does, the group waits on that `SdfMeshBakeShare` (holding no lattice) and
  takes the leader's mesh from the library when it lands (`TakeLanded`, the
  same take a follower in one restart makes, on the pool); otherwise it leads a share of its own. The leader's `Done` and
  `Retired` setters are the one door a share resolves by, under the library's
  gate, so no group joins a resolved share. A waiter whose leader left nothing
  in the library (retired, failed, mesh trimmed) starts again, and one whose
  leader's bake was asked no take while its own was (`DesertStalled`: a
  residency no frame renders) deserts and leads. A waiter's priority raises its
  leader's. The start line counts `joined=`, the done line
  `joined=[groups,landed,abandoned,stalled,samples-saved]`, and
  `world.counters sdf.mesh-shares` reads the library's totals. The share is a
  stop type of the bake's code identity: who bakes a geometry never changes what
  it meshes.
- **Large static groups draw in chunks.** A union, and one shape whose contour reaches
  `SdfMeshChunks.WholeTriangles` (a 500,000-triangle terrain held one worker for its whole collapse), is chunked;
  a smaller single shape stays whole, since locked seams tripled a terrain sector's first level. A mesh that would
  fill more than `SdfMeshChunks.MostChunks` 8 m bins takes bins of twice the side until it fills no more: the world
  group's far ground cut at 8 m makes 160,000 draws, too many to cull and
  level on the CPU for every pass, so `frame/sdf-mesh-selection.hlsli` selects them through the existing counted indirect
  path; chunk sizing still controls retained geometry and candidate work.
  `SdfMeshChunks` merges the contour's planar regions first, then partitions the
  merged triangles by centroid into 8 m bins before collapse. Splitting first
  locks artificial rows of contour vertices along otherwise flat faces and
  makes every later level keep them. It never clips a triangle: each chunk's box includes its whole
  triangles. The merge keeps every open-edge vertex and the collapse locks them, so every level shares the exact seam
  edges with its neighbours. `SdfMesh.Chunks` holds the separately levelled draws; the parent holds the joined vertex
  and triangle attributes the chunks view, and never enters the GPU region. The store writes only the chunks; an offline
  decode joins their indices for whole-group queries (the audit), and a published (native) parent keeps none, since the
  region, the irradiance scene and the store all read the chunks. Dynamic groups and glass stay whole; glass skips collapse because its pass always draws level
  zero. The existing per-draw box cull and detail selector apply to each chunk without shader changes.
- **A glass instance is a group of its own** (`SdfMeshBakeGroup.Glass`, from
  `SdfProgram.IsGlassRange`): it never joins a static run and no instance joins
  it, whatever either declares, and a dynamic group is glass only while every
  instance on its slot is. The stampers emit a creation's glass shapes as one
  static instance after its opaque ones (`WorldPlacementStamper`, with a field
  scope of their own when one blends other than by union) and a pooled
  creation's each on its own slot, before any text-coupled instance opens
  (`WorldCreationInstances.Emit`). A glass draw (`SdfMeshDraw.Glass`) is drawn by the
  glass pass alone and stays out of the mesh pass, the cascades and the
  irradiance scene (`SdfMeshDraw.IsStatic`).
- **Every shape declares its spacing by one rule.** `WorldShapeDetail.Of`
  serves a static stamp's shape, a pooled blend group's part and an ungrouped
  pooled shape alike, feeding `SdfInstanceRange.Detail` and
  `SdfInstancePart.Detail`. A bound measures a shape's reach, not its smallest
  feature, so each feature declares a spacing: a round section (a sphere's, an
  ellipsoid's middle radius, a superellipsoid's tightened by its exponent, a
  cylinder's or cone's, a capsule's, a torus's tube, a strand's thicker radius,
  an elliptic profile's tightest bend, a rounded or convex profile's corner)
  bakes at `SdfSampledLattice.RoundCell`, the finer of a third of its radius
  (each cell turns under the contour's 25-degree crease split, so it shades
  round) and the cell whose chord strays at most `SilhouetteError` (0.2 mm,
  half a pixel at the closest camera) inside it, so a drum's or a lens's
  outline is round, not a 30-gon. A rounding of 5 mm or more declares its
  radius: a fillet about a cell wide otherwise contours as a staircase,
  crease or face cell by cell (the Moth's seat plate), while a narrower one is
  a crease the contour keeps sharp. A plate longer than eight of its
  half-thicknesses declares its half thickness, and a folded shape its copies'
  smallest half extent, since a lattice sized by its length or its copies'
  span steps clean over the sheet. A shell declares a quarter of its
  thickness, a warped shape a thirty-second of its smallest half extent and
  cellular relief a thirty-second of its wavelength. A sine relief or a warp
  also declares its crest's bend (`ShapeWarpDocument.ReliefRadius`, one over
  amplitude times the largest frequency squared) at `RoundCell`, since a
  lattice sized by a large shape's extent facets a relief only a few of its
  cells long. A blend's seam is a
  feature neither shape's bound measures, so a shape with a `smooth` blend
  declares it: a smooth, pipe or groove seam turns at `smooth` (`RoundCell`),
  a chamfer's bevel is a face `smooth` wide (half of it), stairs are `steps`
  turns each; the pipe and groove exhibits refined nothing before this term
  and contoured their 4 cm bead on 27 mm cells. The finest applies, at
  placement scale, no finer than 2 mm (`WorldShapeDetail.FinestDetail`); a
  part thinner than the floor declares the floor (a 1.2 mm eyelid tube that
  declared nothing contoured as shards on a 2.4 mm lattice). A creation emitted
  as one scoped instance (static, or a moving root's surface) declares a part
  a shape and one for its noise relief (`WorldShapeDetail.PartsOf`,
  `SdfInstanceRange.Parts`): each shape's box at its own detail, and the
  relief's spacing (`CreationNoiseDocument.DetailSpacing`) over the box its
  composed surface lies in (`SdfBoundAlgebra.ComposeBox`), so the group bakes on
  a union's final lattice and a moraine's 9 cm round section refines its own
  box, not a whole terrain sector. Text declares a third of its thinnest stroke
  (`SdfProgramBuilder.GlyphDetail`). Refinement stops at
  eight cells a coarse axis (a fitted text group's lattice is spaced to reach
  its detail instead, below), and the fine-sample budget
  (`SdfSampledLattice.MaxFineSamples`) takes a coarser split where the cells a
  region covers would pass it: the debug world's north-west wall, whose relief
  region covers about 128 thousand 7.5 m cells, splits each in three and bakes
  at 2.5 m against the 1.56 m its relief declares
  ([the terrain pass](../../../../docs/plans/terrain-pass.md#what-set-a-sectors-cell)). A surface that large reaches
  its declared spacing only split across lattices, the streaming plan's source
  tiles. A declaration bounds refinement; the bake
  decides its cost (next bullets): a detail at or past the lattice's own
  spacing refines nothing, alone (`SdfMeshPathBake.OwnFinal`) or in a union
  (`UnionFinal`). In a static union a member's region is its own world-axis box
  where the stamper knows one (`SdfInstanceRange.Box`,
  `CreationStampEmitter.ShapeStampBox`: an unwarped, unfolded primitive), not
  its bound sphere's cube, which for a 48 m strip spans the whole slab it hangs
  from. Convex rounding reads the scaled polygon's inradius and extrusion
  clamp; extents use `SdfSolidGeometry.HalfExtent`, since a revolve's scale Z is
  an offset and may be zero while its radial extent remains positive.
- **A declaration is bounded by what a view resolves: the group's tier.**
  `SdfMeshTier` is one ladder of cells (1 mm times two to the tier). A group's
  tier floors every spacing its refinement aims for (`OwnFinal`, `UnionFinal`
  and `FactorOf` take `SdfMeshTier.Cell(group.Tier)` as the floor of a member's
  detail, `FineCell` and `MemberCell`; every factor is still at least two, so a
  lattice at its floor refines the cells `Refine` finds it cannot resolve at all,
  a sheet, gap or tip thinner than a cell, which would otherwise lose the feature's
  whole extent), and is a fact of the sealed geometry
  (`SdfMeshBakeGroup.Seal` appends it, `Fact.Tier`), so each tier of a
  geometry is its own library and store entry. A residency's bake plans each
  group at the coarsest tier whose cell stays under half a display pixel at
  the group's box from the nearest demand point (`SdfMeshDemand.PixelAt`,
  `SdfMeshTier.Of`; at 1080 lines and a 60-degree field, 2 mm within 3.7 m,
  4 mm to 7.5 m, 8 mm to 15 m, 16 mm to 30 m), held between the rungs that
  change its mesh (`FinestTier`, the finest spacing any member asks;
  `CoarsestTier`, the planned final cell, past which nothing refines). With
  no demand point a group plans at its coarsest; an offline bake
  (`MeshCpuBake`, `puck mesh audit --cpu`) sets `SdfMeshPathBake.PlannedTier`
  and takes each group's finest unless `--tier` or `--eye` says otherwise. A
  landed group whose demanded tier has been finer than its own for
  `SdfMeshTier.HoldFrames` frames is planned again at the finer tier and placed
  as a replacement (`SdfMeshPathBake.Retier`, its `Replaces` path, at most
  `MaxInFlight` at once, the finest demand first; an arrival's landed floors
  start their first details `SdfMeshTier.FirstsPerFrame` a frame, `StartFirsts`,
  and a replan plans only the group's own instances, `SdfMeshBakeGroup.Refresh`,
  never its slot's other groups or the program's other instances): the coarser mesh draws
  until the finer is baked and its words stand in the mesh region
  (`FinishReplacements`; the swap bullet below). The demand is measured a share of the groups each frame
  (`SdfMeshPathBake.MeasureDemands`, one sweep of every group's boxes in
  `SdfMeshTier.MeasureFrames` frames), so its cost a frame does not grow
  with the resident world; `Retier` decides the tiers from the measured
  pixels once a measure, since no pixel moves faster, and a frame between
  decisions pays the measure's share alone. A bake whose groups have all landed can still owe
  the tiers its demand moved to, which `SdfMeshPathBake.Pending` does not
  say: `SdfMeshPathBake.DetailSettled` does, once `Retier` has replaced
  nothing, had nothing landing or waiting its hold, and pressed on nothing
  it can still coarsen for `SdfMeshTier.SettleFrames` frames, and
  `world.wait bakes` waits on both for the world's own residency, that
  many frames after it armed. With room in the mesh region a coarser tier demanded leaves the
  finer mesh where it is. The region's budget
  (`SdfMeshTier.BudgetEighths` of `SdfWorldTables.MeshRegionLimitBytes`, read
  each frame by `SdfMeshPathBake.ObserveResidency`) decides the rest in
  `Retier`: a finer tier starts only while the bytes the draws name leave it
  room; while the budget presses, the groups drawing a finer tier than their
  demand asks are planned again at the demanded one, the largest saving
  first; and when it presses with nothing spare every demand is coarsened
  half a rung (`SdfMeshTier.Biased`), taken back once the finer demand would
  fit again. The first plan is budgeted the same way from the plan's own
  measure. `world.residency` reports `tiers-owed`, `owed-error` (the worst
  owing group's resident cell in display pixels), `owed-frames`, the worst of
  each since the bake started, `retiers`, the resident triangles by tier, the
  budget's account (`region-budget`, `region-named`, `tiers-spare`,
  `tiers-held-back`, `coarsened`, `detail-bias`, `bias-raised`,
  `bias-lowered`) and, per demand point, the groups and triangles that point
  sets the tier of ([the memo](../../../../docs/plans/bake-demand-tiers.md)).
  A stop that settles with `detail-bias` above zero is drawing coarser than
  half a pixel there: the demand is past the budget, which is the reading to
  act on, never a raised limit.
- **A group arrives at its floor and keeps it.** A residency's group that
  arrives in view with nothing to draw (no group at its selector, or one still
  bringing its floor, `SdfMeshPathBake.Arrives`; in view is
  `SdfMeshDemand.Sees`, every box with no demand point) plans its coarsest
  tier first (`SdfMeshPathBake.Tiers`), so a place lands whole and coarse
  before it is sharp. One arriving out of view plans its demanded tier at
  once and keeps no floor: floors are about a quarter of a cold bake's pool
  work, and no view waits on that place. Every take and every worker stage
  orders the groups in view ahead of those out of it, each side by the
  demand's priority (`SdfMeshPathBake.RankOf`). Once that floor has landed,
  the next tier decision starts the demanded tier as the arrival's own bake
  (`Group.FirstDetail`): no hold, outside `MaxInFlight` and the budget, as a
  first plan at that tier would have baked. Until then the bake owes the frame
  (`Owes`, `IrradiancePending`), so a lockstep still or `world.wait bakes`
  never settles on floors. The detail lands ahead of the draws beside the
  floor and keeps the floor with a claim of its own (`Group.KeptFloor`, taken
  in `ShowReplaced`, the one place a replacement inherits from the group it
  replaces); the kept floors are named ahead with the waiting products so
  their words stay in the region. A finer tier the region refuses over a
  standing kept floor is evicted to it at the next frame
  (`SdfMeshPathBake.Evict`): the floor takes the draws at once where it was
  baked from the geometry the plan reads, and is baked as a coarser
  replacement otherwise; an evicted floor takes detail back only through the
  budget. A group taken whole from the library, or replanned while it drew,
  keeps no floor until it arrives again. `world.residency`'s floor line
  (`SdfMeshPathBake.DescribeFloors`) counts floors shown, pending, empty,
  failed and kept, groups with none, first details owed and landed,
  evictions and their bytes, `holes` (groups in reach, demanded past a pixel,
  drawing no standing mesh) and `hole-frames`, and the floors' bytes by
  class. The floor is the coarsest rung only: a floor that meshes nothing is
  counted `floor-empty` and its group goes straight to its detail, with no
  finer rung tried and no coverage check yet
  ([step 5](../../../../docs/plans/streaming-and-memory.md#step-5-the-floor-and-eviction)).
- **A region refines only where its surface turns, and each region at its own
  factor.** `SdfSampledLattice.Refine` takes a factor per region
  (`SdfLatticeRegion.Factor`): `UnionFinal` asks each member's own
  (`SdfMeshPathBake.RegionFactor`), so one fine member refines no other
  member's box, and the lattice's split is the finest region's. Inside a region
  a cell refines only where the coarse samples' second differences show the
  surface turning (`CurvedSplit`: a plane's field is affine and contours
  exactly), each to the factor its curvature needs under `RoundCell`, never
  past its region's. A cell's split is the refinement's own divided by a power
  of two, so every split divides the finest; a measured cell of a coarser split
  measures only its stride's grid of fine samples and interpolates the rest
  inside each stride cell (`StrideHolder`, the finest holder of a shared face
  answering for both sides), and the contour merges each stride cell's fine
  vertices per connected piece, as it merges an unmeasured ring cell's
  (`SdfDualContouring.Merge`), so its triangles follow its own split. The
  value-only test cannot tell a sharp crease or a sub-cell fillet from a tight
  turn, so a declared region still refines its creases.
- **A tall union misses thin layers.** One static creation holding stacked
  floors bakes as one union whose lattice is sized by its height, so a 0.3 m
  slab between two samples never crosses and is dropped while it still
  collides. Give each storey's floor its own prototype and placement
  (`worlds/debug/hall.puck`), so each is a flat group. Trim set into a large
  union is the same case: the hall's walls bake at 15 cm, so the cassettes at
  their window heads, set 2 cm and 5 cm back from the wall's faces, are a row
  per level and face of their own (`hall-cassettes-*`), each baking at 5 cm.
- **Text bakes over its glyphs' box, without the coarse search.** An instance
  holding text alone is fitted (`SdfInstanceRange.Fitted`): the builder
  unions each glyph cell's box as `SdfProgramBuilder.Text` emits it and
  `EndInstance` declares the union as the instance's box (a static instance)
  or its one part (a dynamic one on the glyphs' slot). A group whose every
  instance is fitted takes the union of those boxes
  (`SdfMeshBakeGroup.Fit`) and goes straight to its final lattice
  (`SdfMeshPathBake.StartFinal`). The search samples a bound at a spacing the
  bound sets, and a line of strokes thinner than that spacing reads far from
  the surface wherever a column falls between two strokes, so the narrowed
  box cut the first words off the gallery plaques' notes. An emitter that
  knows its surface's box exactly declares it the same way; a box with a
  margin about the surface is not fitted. A stroke about one fine cell wide
  tears or bridges to its neighbour, and one two cells wide is the margin
  itself: a sans face's arms are thinner than its stems (Inter's are 0.082 em),
  and the gallery's label-only plaques, at half a 0.1 em stroke, baked no finer
  than 3.7 mm cells, under two cells across those arms. A run asks a third of
  its thinnest stroke (`SdfProgramBuilder.GlyphDetail`, from
  `GlyphStrokeEms`; `WorldPlacementStamper.TextDetail` declares it), and a
  fitted group whose length-spaced lattice cannot reach that detail within
  `MaxDetailRefinement` cells takes a lattice that many details apart
  (`SdfMeshPathBake.OwnFinal`, budgeted as a union's by `BudgetedLattice`). A
  fitted text group's lattice keeps only three samples across its slab
  (`TextMinimum`, not `FinalMinimum`): every cell its glyphs can enter refines,
  and nine samples across a slab a centimetre deep would have the refinement
  split sub-millimetre cells as many times as the strokes' cells, spending the
  fine-sample budget (`SdfSampledLattice.MaxFineSamples`) across the slab's
  depth and leaving a long note a coarser split. The tier floors the detail, so a view that
  resolves no stroke pays for none, and a group baked at a tier coarser than its glyphs
  declare thickens them instead of losing strokes: the lettering stroke rule in `sdfGlyph`
  widens the thinnest stroke toward `GlyphThickenCells` cells within the atlas's band and the
  relief to one cell, or bakes the glyph as its ink box where the stroke stays under
  `GlyphHoldCells` cells
  ([text and glyphs](../../../../docs/rendering/sdf/reference/text-and-glyphs.md#the-lettering-stroke-rule)).
  Every lattice of a group takes the group's cell and stroke through one door
  (`SdfMeshPathBake.RequestOf`, `SdfMeshBakeRequest.Glyphs`), so coarse and fine samples
  read one field; a lattice built around that door bakes the glyph unthickened beside
  thickened neighbours. A
  glyph's field is its atlas distance only within half the atlas's distance
  range of an edge and a bound past it (a constant band, then its cell's box),
  so a static instance's glyphs (`SdfInstanceRange.Glyphs`, joined into
  `SdfMeshBakeGroup.Glyphs`) are a region of their own, at their own detail, in
  which every cell the surface can enter refines (`SdfLatticeRegion.Bound`): a
  cell whose samples sat on that band read flat and skipped the refinement,
  losing an i's dot or a full stop between them. Lettering engraved into a
  scoped creation refines only that box, never the creation's whole surface.
- **The coarse narrowing keeps the rows a thin plate lies between.** The
  narrowing (`SdfMeshPathBake.Refine`) keeps a sample within half the lattice's
  finest spacing of the surface, beside a sign change, or in a pair of rows a
  sheet thinner than the spacing passes between
  (`SdfSampledLattice.SheetsBetween`), and a final lattice all of one sign
  refines when that test finds a sheet rather than finishing empty. The pair
  test reads one line: the field falls toward the pair from both sides, the
  falls meet strictly below the surface (a sheet's meet below it by half its
  thickness; the falls either side of a solid's grazed edge meet above it), the
  field changes across the line by under three quarters of a step at the
  line's own slope (a line a step over a plate's top or a step out from a
  board's face falls or rises by the whole step across it), and neither sample
  is within the distance test's reach, so the pair moves the box only where
  the distance test loses the sheet. A pair's samples join the box with one
  cell about them, which keeps the sheet off the next lattice's edge, whose
  outermost pair no line can test. Loosened, each of these moved the box of
  groups that never needed it by a coarse cell and changed their final
  lattice's alignment (the ground slab's lattice went from flat to cubic and
  its clean mesh to 1.3 M rippled triangles; a canvas or sign scored four times
  worse or better by where its faces fell), so a change here is measured by
  `puck mesh audit --cpu` over the whole debug world against the previous
  build's. The pair test is what keeps a 6 cm strip lying between sample rows
  of a 1.8 m coarse cube in the box while its neighbour a row lands near is
  kept by the distance test (`SdfMeshPathBakeLawTests`, the plates law: four
  standalone 48 m strips); keeping samples within half a cell's diagonal
  instead fattens the converged box until the final lattice steps over the
  plates and the group bakes nothing. `hall.puck`'s strips ride each slab (`hallStrips`) as thin
  trim of the solid they hang from, which also keeps a level's lit and dark
  looks one geometry. The bake caps declared-detail refinement at eight cells
  per coarse axis.
- **A pooled blend group bakes as a union of its parts.** Its one instance
  declares a part a shape (`SdfInstanceRange.Parts`, `SdfInstancePart`): the
  shape's box in its own slot's frame and its detail. The plan carries each box
  into the group's frame through the pose the geometry hashed for that slot
  (`SdfMeshBakeGroup.AddDynamicMembers`), and each becomes a member
  (`SdfMeshBakeGroup.Members`), so a group of several members bakes on
  `UnionFinal` as a static copy's run does: a cubic lattice at the union's own
  spacing, not `OwnFinal`'s `MinimumCell` floor, refined per member. A dynamic
  slot holding several instances without parts unions their spheres the same
  way. Parts are hashed into the geometry by slot offset. Under `OwnFinal` an
  18 cm swallow's blend group bakes on a 15 mm lattice refined over its whole
  bound; under `UnionFinal` it starts at the 2.8 mm its static stamp's union
  takes, each member refined over its own box at its own factor. A folded
  member's part is the cube about its slot's origin its copies reach.
  A dynamic instance's text declares detail too: a pooled creation's embossed text is
  its own instance on a slot after its shapes' that holds the root's pose,
  bounded by its glyphs' reach and declaring their
  detail. Sharing the root slot with a blend group put the glyphs in that
  group's coarser lattice, which dropped an "I". A slot's group refines toward
  the finest detail its
  instances declare over their bounds (`SdfMeshBakeGroup.Detail`). Engraved
  text stays in one scoped instance with the shapes it carves.
- **A screen slab is a static instance of its own** (`WorldScreenStamper`),
  bounded by the slab and declaring its thickness as detail. Segments no
  instance owns bake in the world group, one lattice the far distance wide,
  too coarse to hold a centimetre-thick slab or keep the body behind it off its
  face.
- **The bake samples through the interpreter**, in the fragment's `mask` and
  `bake` parts, only while `SdfMeshPathBake.Pending`.
  `sdfMapOmitWorldSegments` (bake only) drops unowned segments, which bake as
  their own group. The bake's own pass block (`sdf-mesh-bake.interface.hlsli`)
  and its lattice rows are a sync pair with `SdfMeshBakeBlock.Write`.
- **A bake never reads the frame's transforms.** A dynamic group's box,
  lattices and points are slot-local, and `sdf-mesh-bake` reads every transform
  through the poses the group's geometry hashed (`SdfMeshGeometryBuilder.Poses`,
  staged after the batch's points, named by each lattice's fourth row,
  `SDF_MESH_BAKE_POSES`), so a mesh is a function of its geometry: a body moving
  while it bakes bakes whole, and two boots of one device bake alike. The
  contour is the mesh, already in that frame.
- **A dynamic body bakes at its own size.** The pool (`WorldCreationInstances.EmitOne`)
  and the rig catalog emit a body's geometry in its slots' own units, whatever
  its look's or `bodies.scale` register's scale, and every slot carries that
  scale (`DynamicTransform.Scale`; positions stay world positions, and field
  transforms stay rigid). The geometry builder reads another slot's offset from
  the group's slot in the group's units (`SdfMeshGeometryBuilder.RelativePose`,
  `UnitsOf`), as an operand's snapped pose is, so the key, the detail and the lattice
  are the full-size body's; the group's draw matrix takes the scale
  (`SdfMeshDresser.Dress`), and a member's vertex takes the draw's scale
  (`sdfMeshDrawScale`, the current and previous positions). A body crossing a
  portal pair of two sizes (Wonderland) bakes nothing and draws its full-size
  mesh scaled. Its material layers stay in world units at its scale, since the
  shading reads the slots' world poses. Never fold a body's scale back into its
  emitted geometry: a quarter-size body then keys new geometry and bakes four
  times coarser relative to itself. A slice (`world.slice`) walks the field
  through the frame's rigid transforms, so it shows a scaled body at its own
  size about its slots.
- **Materials are point-sampled, not taken from the lattice.** Each final
  quad's quarters and vertices are sampled through `sdfMeshBakePoints` (a staged
  World table the residency writes before the upload); a quad whose quarters
  disagree splits into them, taking one vertex at the middle of each of its
  edges that the triangle across the edge splits at too (found by position, so a
  cut's boundary point that landed on an end counts), leaving no T-junction for
  the audit to count as an open edge, and one whose vertices disagree is cut along the
  boundary its edges' bisection finds (`SdfMeshMaterialCut`). Two shapes that meet at a crease change
  material at the crease vertex itself, while a point lifted off the chord across the crease reads either
  shape a round or two out from it, so a boundary within the quarter of an edge next to a crease vertex
  (`SdfContour.Features`) lies at that vertex (`SdfMeshMaterialCut.Boundary`), or the cut lays a sliver
  along the rim that turns out of both faces. `SdfMeshMaterialCut.Build` holds its lists to
  `MaxTrianglesPerQuad` and `MaxVerticesPerQuad` for each contour quad, checked in one place (`Within`, after every
  growth); a cut past them throws `InvalidOperationException`, which `SdfMeshPathBake.Build` reports as
  `group <n> refused: the material cut of …` and lands the group as a refused mesh. A material
  boundary only lies on the surface within one group: two groups' shapes meet
  as crossing meshes, whatever their materials.
- **Moving blends bake at authored rest.** The pooled emitter marks its delta-frame instances
  `RestPoseSkin`; `SdfMeshGeometryBuilder` freezes those deltas at identity. `CreationMotion.Envelope`
  admits bounded smooth seams, and `CreationMotionPlan.RenderDocument` partitions rejected groups by
  motion owner before emission. The CPU `SdfMeshSkin.Build` round propagates owner shares through the
  evaluator, once per exact position; every crease/material copy takes that tuple. Twelve packed bytes
  in `SdfMesh.Influences` carry a second owner, share and gradient. A third share above 1/64 falls back
  to rigid owner contours through the existing contour pipeline. Current, previous and shadow positions
  share group-relative dual quaternions and corrected normals (`frame/sdf-mesh-skin.hlsli`). See
  [moving blends](../SKILL.md#moving-blends) for the complete contract and checks.
- **A skin bakes once.** A skinned group bakes at the pose its program arrived in (a rest skin at rest) and
  is never baked again for its members' motion. A moving cutter is an operand instead, and its group is
  planned again through `SdfMeshPathBake.Revisit` as the operand moves a step
  ([moving blends](../SKILL.md#moving-blends)). `sdfLayerFrame` interpolates rest coordinates and lanes
  through the skin. The lead's presented striped-neck burst checks the material result in motion.
- **A landing mesh rebuilds the draws.** A group that bakes again draws the mesh
  it replaces until its own lands, so it counts as drawn already; `Land` and
  `Load` hand the new mesh over through `SdfMeshPathBake.Draw`, which marks the
  draws stale, or a still group keeps drawing the old mesh.
- **Every landed mesh is merged into its planar polygons** (`SdfMeshPlanarMerge`,
  called in `SdfMeshPathBake.Land` before the library stores it), so the store
  keeps, every pass draws and the irradiance trace reads the merged mesh. A
  region is a run of triangles across shared edges with one material, one member,
  one normal bit for bit at every vertex and every vertex within 2^-21 of its
  plane relative to its coordinates; a vertex only its region names, whose
  triangles close a ring about it, is removed and its hole ear-clipped again under
  exact float orientation tests, then flipped toward Delaunay. Every outline vertex
  stays, a straight run two merged faces share included (dropping it from both
  sides keeps the geometry but has the rasterizer snap the shared edge from other
  vertices, for 1.6% of the triangles left). Keep it that way: a change that moves
  or renormals a vertex, or drops an outline vertex, changes pixels. What a
  retriangulated face does change is depth interpolation's rounding, so where it
  meets a separately baked mesh (a plinth's embossed label, a wall's window frame)
  a pixel at the junction can take the other surface: five pixels in three
  settled normals captures of the debug world. The merge leaves curved surfaces
  alone (their vertex normals differ), so it removes about two fifths of the debug
  world's triangles, and its polygons' triangles are long and thin where a face's
  outline is dense: a consumer that bounds triangles by their boxes sees looser
  boxes than the lattice's quads gave, which the trace hierarchy answers by
  boxing such a triangle in pieces (below). The done line counts `merged=`
  triangles; `SdfMeshPlanarMergeLawTests` holds the outline, the area per
  material and normal, and no opened edge.
- **Every landed mesh then collapses into two coarser levels** (`SdfMeshCollapse`,
  `SdfMesh.Levels`, the decision in
  [rendering](../../../../docs/decisions/rendering.md)). A place is a position;
  its copies are the crease split's vertices there. A collapse moves one place's
  copies onto a neighbour's, each side of the collapsed edge taking that side's
  copy, so a level is indices and triangle materials over the merged mesh's
  vertices. Each (vertex, material) of the merged mesh is a sample tracked to a
  triangle; a collapse re-measures the samples about it against the triangles
  that stay (point to triangle in doubles, plus the interpolated normal's angle)
  and is refused when one has none within the level's bounds
  (`CellShares` of the contour cell, `NormalDegrees`). Every crease and material
  edge vertex and edge midpoint is a line sample tracked to the feature edge it
  lies nearest, re-measured point to segment when a collapse moves that edge: the
  surface samples alone let a slide fill a notch in a face's outline (the notch's
  vertices lie inside the filling triangle, at no distance), which drew surface
  past a raised plate's outline several pixels out. `SdfMeshLevel.Error` is the
  largest distance the surface samples, the line samples and the triangle bound
  below measure (raised to the finer level's where
  re-tracking measures a coarser level nearer). Places sort per pass into free (at most one
  crease or material edge, ending there), sliding (two copies: only along the
  crease between them; one copy on material edges: along them) and locked
  (three or more copies, an open or non-manifold edge, a fan that is not one
  ring); a refusal also guards the link condition, a fold past `FlipCosine`, and a
  face turning to the other side of its vertices' normals. A pass locks only the
  places a collapse moved triangles onto, since those places' lists miss them;
  the passes take about half as many collapses each, about twelve a level. A
  third guard bounds each new triangle: its centroid and edge midpoints are
  measured against the old fan's same-material triangles, and each triangle
  carries the largest such distance it inherited, so a collapse cannot cut a
  triangle through a thin rod the samples straddle. On the debug world's stored
  set it keeps 11% of the triangles at the first level and 6% at the second, for
  9% more stored and region bytes. Conservative triangle-box distance bounds
  skip exact measurements that cannot improve the result; they never certify
  acceptance. Reverse edge measurements are shared across targets of an
  unchanged source fan, and unchanged failed edges are not measured again.
  Judge a changed collapse by
  the field audit at each rendered level, not by equality with earlier meshes.
  Glass skips collapse because its pass uses only
  level zero. The done line counts `levelled=` pieces and
  the triangles every mesh draws at `level1=` and `level2=`;
  `SdfMeshCollapseLawTests` measures each level's contract by brute force.

## The mesh region

- **The compact store expands to the fastest GPU layout.** `SdfMeshStoreCodec` chooses bounds-relative
  16/24-bit positions only when every decoded vertex moves by at most `BakeCell.Length()/1024`;
  otherwise positions remain floats. Every chunk shares its group's grid and width, so shared seam
  vertices decode bit-identically. Unit normals use signed oct16 pairs; non-unit authored normals
  retain their magnitudes. Indices use 16 bits through 65,536 vertices and materials use bytes when
  their values fit. Delta-predicted attribute byte planes are zlib-compressed. Decode reads planes
  directly from the decompressed payload into the storage the mesh keeps (`SdfMeshStorage`), a host's native
  blocks or an offline read's arrays, applying the taking group's material ids as the planes are read; a
  restore takes only the normals and the coarser levels' indices.
  Both backends draw six floats per vertex and 32-bit indices/materials through `frame/sdf-mesh.hlsli`.
  `SdfMeshLibrary.TryLoad` coalesces a set entry's decode across groups and keeps its result with the
  library's bounded meshes. A failed read is removed so a later derivation can be loaded.
  Sound entries can also record that a bake found no surface: a successful store read with a null
  mesh is an empty result, not a miss. `StoreEmpty` persists it under the bake identity so fully warm
  boots need no bake dispatch or bake-pipeline creation. Offline consumers skip its absent surface.
  The owner's mesh-compact correction: warm decode must be no slower than the old load, and a
  smaller GPU region is welcome only when mesh and cascade GPU passes are no slower. Measure
  repeated `world.gpu-timing` windows at the same pose; do not infer speed from region bytes.
  Record the presentation target and GPU clocks beside an A/B: the device can downclock at 60 Hz,
  so compare both variants at the same target and frequency range. Keep ordinary-target readings too.

- **Glyph-bearing groups retain their outlines at every distance.**
  `SdfMeshGeometryBuilder.ContainsGlyph` recognizes `ShapeBlend/Glyph` in static, dynamic and unowned
  world groups. `SdfMeshCollapse` caps crease and material-edge error in those groups at the largest
  bake-cell dimension divided by 8 while face interiors use the ordinary level budget; a mesh
  without detectable features retains its base surface. Corners and open edges stay fixed.
  Whole-group collapse exclusion also prevents large scenery sharing a glyph group from coarsening,
  so its cascade cost must be measured before choosing it. A geometric distance budget alone does
  not protect text counters and thin strokes: the lift's lit zero lost its hole near 21 m.

- **Meshes keep their words; draws repack only their records.** The tables
  place each mesh whole in an arena past a reserve of draw records
  (`SdfMeshRegionArena`), where it stays while a draw names it, so
  `StageMeshRegion` (`SdfWorldTables.MeshRegion.cs`) writes the draw records
  (`SdfMeshRegion.WriteDraws`) and only the meshes the arena newly placed. A
  layout that moves placed meshes when one lands (sections by attribute) made
  every landing rewrite the whole region. Placed meshes land through the
  background GPU work, never a frame's upload (`SdfWorldTables.MeshLanding.cs`):
  jobs of at most `SdfGpuWork.MostUploadJobBytes` under its byte, host-time and
  GPU-share budgets, each a rate of wall time and never a count a pump: a
  per-pump budget lands only as fast as frames come, and a window the
  compositor throttles to a few frames a second would take many times
  longer to land the debug world's mesh region. Jobs take the meshes nearest the views first, each staged into the job's own slot
  of the region (`MeshLandingSlot`, past the upload ring's) and copied in the
  job's command buffer. A mesh leaves `m_meshesOwed` only when every job carrying
  its current placement has completed, and the landing filter in
  `SdfWorldTables.StageMeshDraw` writes its rows absent until then; a
  relocation, a moved mesh or a trim drops that mesh's progress, so a job still in
  flight for its old words lands nothing. A frame that stands is staged again
  when a mesh lands (`StageLandedMeshes`), and a lockstep frame waits for the
  landing (`SdfWorldPasses.WaitingOf`). `world.residency`'s
  landing line reads the frame uploads' staged mesh bytes (`frame-staged-most`)
  and the landing jobs. A grown region takes the words it held. A
  list past the draw reserve doubles it and moves only the meshes the grown
  reserve takes (`SdfMeshRegionArena.Moved`), written that frame: relocating
  every mesh for it rewrote and compared the whole region in one frame. The
  region's host copy holds the draw reserve alone: a placed mesh's words are
  owed and the flush writes them from the mesh's own arrays
  (`SdfWorldTables.WriteSourcedMeshWords`), zeros in words no placed mesh holds.
  A placement names absolute words (`SdfMeshRegionMesh`); a new per-draw field
  belongs in the record, never in a mesh's words. The record's layout is
  `SdfMeshRegion`'s, a sync pair with `frame/sdf-mesh.hlsli`
  ([sync pairs](sync-pairs.md#engine-buffers-groups-and-bindings)).
- **A mesh that replaces a drawn one lands before a draw names it.** A
  group's product and the mesh the frame draws for it are two things
  (`SdfMeshPathBake`'s group: its `Mesh` and its `Shown`). Every product
  arrives through the one setter, whatever made it: a finer or coarser
  tier, a resample, an operand's step, a new program's plan, a renumbered
  mesh. Where a residency's tables land the bake's meshes, a product that
  replaces a drawn mesh waits ahead of the draws: the bake names its pieces
  to the tables (`SdfMeshPathBake.ObserveResidency` into
  `SdfWorldTables.NameMeshesAhead`), the arena places them beside the
  meshes the draws read (`SdfMeshRegionArena.PlanAhead`) and keeps them like
  a named mesh, they land after the meshes a draw waits on, and the group
  takes the draws only once the tables say every piece stands
  (`SdfWorldTables.MeshStands`). So a swap holds no draw out of a frame, and
  a mesh landing ahead stages no draw again: only the hand-over does. The
  standing products take the draws together, once none is still landing or
  one has waited `SdfMeshTier.HandFrames`, so a wave of replacements moves
  the draws every view renders from once. The hand-over stages its own
  rows: the dresser replaces a group's bindings in their run when its
  piece and copy counts stand, so its journal names those rows alone;
  `SdfWorldTables.StageMeshRegion` moves each changed name through the arena's
  row transaction and stages only those rows. A piece/copy-count change
  reallocates that group's run, preserving every unrelated row. Only a start
  over (failure retry, the free share, a forced pack or locked canonical order)
  rebuilds all owners. Claims and glass counts move inside the row writer.
  `SdfMeshPathBake.Pending` stays true while a product waits, so
  `world.wait bakes` and a lockstep frame wait for it;
  `SdfMeshPathBake.DrawsPending` leaves the waiting products out, and a
  view's standing render is judged by it
  (`SdfWorldResidency.IsUnchanged`), since nothing a view draws moves until
  the hand-over. The owed meshes named ahead land from a list of their own,
  listed again whenever the set changes (`SdfWorldTables.MeshLanding.cs`):
  the roster's landing order is rebuilt only when a draw list is planned,
  which a hand-over no longer does. The guarantee stops
  at a group's first mesh, which has nothing to keep drawing, at a bake no
  tables observe (an offline bake draws each product at once), and at a
  piece the region has no room for beside the mesh it replaces
  (`SdfMeshRegionArena.AheadRefused`): that product takes the draws anyway,
  and the piece lands in the words the old mesh gives up, out of the frame
  until it does. `world.residency` counts the products that took their
  draws (`handed`, with `handed-refused` for the last case) and those
  waiting (`ahead`).
- **One region holds every resident mesh, up to what its grant reserves.**
  Before a plan the tables reserve the standing buffer and a replacement
  together in the process account (`SdfResidencyGrant.ReserveGrowth`,
  `SdfWorldTables.MeshRegionLimitBytes`), never past
  `SdfWorldTables.MostMeshRegionBytes` (`GpuRegion.MaxByteCount`, just under
  4 GiB), and the arena places nothing past it (`SdfMeshRegionArena.SetLimit`),
  so the region, the copy a growth holds until its upload completes and
  everything else the device holds fit together. A growth the account or the
  device refuses leaves the region as it is (`SdfMeshRegionArena.Clip`). It grows to its need plus an eighth, rounded up to a
  16 MiB granule and capped at the limit
  (`SdfWorldTables.MeshRegionGrownBytes`, a pure function), so it reads
  fuller than a doubling would; `world.budget` prints the bytes the staged
  draws use (`MeshRegionUsedBytes`) beside the bytes held and the limit.
  The arena places each mesh in the lowest free run under the limit
  (`SdfMeshRegionArena`, over `GpuRangeAllocator`) and gives a forgotten
  mesh's words to the next mesh they hold, so a group changing tier moves no
  other mesh. A mesh that finds no run is refused
  (`SdfMeshRegionArena.Refused`, `refused` and `refusals` on
  `world.residency`'s landing line): its draws wait out of the staged
  records, which shows as a hole, and nothing throws. The bake keeps the
  named bytes under its budget so that a refusal is the exception (the tier
  bullet above); a run with `refusals` above zero has a demand the budget's
  law did not hold. A growth the device itself refuses under the limit
  (`GpuRegion.Grow`) still stops the host. The ceiling is the whole uints
  below 4 GiB less the staging
  buffer's header and run table, because a staged region's staging buffer binds
  as one storage view and Vulkan states a view's range in a uint32. `GpuRegion`
  counts bytes in a `long` and words in an `int`: a mesh's byte offset is
  `((long)VertexWord) * sizeof(uint)`, `Contents` refuses past `int.MaxValue`
  bytes, and a piece of the host copy is read through `ContentsAt(offset,
  length)` (`SdfWorldTables.StageChangedDraws` reads only the draw records that way). Host writes
  go to a buffer in pieces of at most 1 GiB. No run of the debug world reaches
  2 GiB, so `GpuResidencyLawTests` holds a 3 GiB region written and flushed
  through buffers that record their writes, and `SdfWorldTablesUploadLawTests`
  holds the growth arithmetic past 2 GiB.
- **A jump in planned groups is usually a population change.** Every pooled
  body adds one dynamic group a slot, so a body that starts wearing a large
  creation multiplies `groups=` and `dynamic=` in the `[sdf.mesh-bake] start`
  line. A `state.body` register selector whose case names the register's
  initial value selects every body: the suit selector once dressed every chess
  piece and the board cursor as the Moth, and the debug world planned 7,322
  groups, 6,880 dynamic, in place of about 1,286 and 844. The validator refuses
  such a case (`WorldDefinitionValidator.ValidateRowSelector`); `body.rig <n>` names the creation a body wears.
- **A group a later program drops before it lands is never stored,** so it bakes
  again on every boot. A boot whose second `[sdf.mesh-bake] start` line plans
  fewer groups than its first, and whose next boot's first start still reads
  `baking=` above zero, presented a document its first tick then changed. A
  placement's response mask is settled into the booting document
  (`WorldStateSettlement.SettleResponses`), so the debug world's raised blinds
  never reach the first plan; look for another tick-one change (a rule, a deal)
  when the line comes back.
- **The bake is background GPU work under a budget.** The residency's tables
  own one `SdfGpuWork`: a ring of `SdfGpuWork.SlotCount` slots, each a command
  buffer, a submission fence, a readback and two timestamps, which its bake
  client (`SdfMeshBakeGpuWork`) fills with one batch a slot (`TryTake`: up to
  `SdfWorldPackage.MeshBakeBatch` lattices, 240, whose rows fill the bake pass
  block to the portable 16 KiB uniform limit; `MeshBakeMaxSamples` samples,
  2^21, 32,768 groups of 64, under the 65,535 a dispatch axis allows; and
  `SdfMeshPathBake.BatchTaps` field evaluations, a gradient sample counting
  five). A batch is the mask dispatch, the sampler dispatch and the samples'
  copy back, submitted on its slot's fence; the kernel finds a sample's lattice
  by binary search over their first samples. Each lattice names its output word offset
  and fields in the last word of its fifth row. Box refinement and root searches read
  distance, material cuts read material, fine samples and slabs read both, and measured
  normals and slices read distance followed by gradient triples. Slabs fill the final
  lattice after their ticket is claimed. The CPU sampler writes the same planes through
  `SdfMeshBakeRequest.WriteSample`. `Pump` runs on the frame thread
  (the GPU layer records and submits on that thread alone) at the top of each
  frame, before any residency prepares, and after each upload: it hands every
  job whose fence signaled to its client, which copies and decodes the samples
  on the bake's pool and releases the slot (`SdfGpuWorkReadback.Release`), and
  refills every released slot while the budget holds. Between two frames the
  host's wait takes the same step (`HostWaits.Pace`, the service's
  `WaitService`): the frame thread sleeps on its deadline and one wake
  together, and a job's fence (`IGpuSubmissionFence.SignalOnCompletion`), a
  lattice a worker readied (`SdfMeshPathBake.Offered`), a released readback
  and the budget's next credit each end the sleep early, so a batch is
  answered when it completes and the next taken when it is ready, whatever
  the frame rate. Such a step takes no job within `SdfGpuWork.HostBudget` of
  the wait's deadline. The budget is
  the share of the GPU's time the frame leaves free (`SdfGpuWorkBudget.Share`, at most `SdfGpuWork.GpuShare`), charged by each job's own
  timestamps (the bake's mean-following rate, from a prior of `NanosecondsPerTap`, until they land or on a
  queue without them), banking at most a short spell while idle. A job binds the
  latest upload's World set only while nothing it binds has moved since that
  upload and the tables' uploaded program is the bake's
  (`SdfWorldTables.BindsBackgroundWork`, `BackgroundProgram`): between a pack
  and its upload the slot's buffers are owed contents not yet sent. Every
  lattice is chunked to fit `SdfMeshPathBake.LatticeTaps` (final lattices in
  slabs, material and gradient, fine and material points in chunks). The done
  line's `gpu-work=[…]` reads jobs, their measured GPU time, the wall time some
  job was in flight and the GPU's share of it, the most in flight, the steps
  (`pumps`), those taken inside the host's wait and the jobs they submitted
  (`services`, `service-jobs`), the drives of held frames and their waits, the
  steps the World set could not be bound in, those the budget held, the jobs
  handed back for want of device room (`deferred`) and the waits a lease made
  the tables take (`lease-waits`, zero on one queue);
  `world.gpu-timing` does not see the work. A slot's buffers are the
  service's, created through one door that reserves them before the device is
  asked (`SdfGpuWorkRecording.HostBuffer`, `DeviceBuffer`, `CopyToReadback`,
  `ReserveReadback`; workspace under `SdfResidencySelector.WorkOwner`) and that
  creates nothing once the job has consumed state (`CopyRegion` takes a
  region's owed words): a job asks for every buffer, its readback reserved,
  before it copies a region, so a refusal hands it back whole. A client's own
  cache initialization (the probe hit cache's clear, the meter cache's fill)
  stays owed until a job that recorded it completes. Its readback and the
  bake's point table, sampled table, masks and samples grow to the slot's
  largest batch and go once no job has needed them at that size for
  `SdfGpuWork.IdleSeconds`, so a settled bake holds none;
  `world.residency`'s `gpu-work` line reads what remains and what is
  reserved. A client keeps what it wrote into a buffer, or the sets that name
  it, by comparing the buffer's object: a replaced one is another object. A
  batch the pool has no room for goes back to the bake (`Abandon`), which is
  offered a slot again once one comes back; a client with no slot in use
  reserves its batch as the floor. Admission of a group's final lattice waits
  on the pool's backlog measured as wall time (`SdfMeshBakeBacklog`): the
  stages queued and on their way against what the workers drain in an
  admission's lead. Gradients are measured only at the
  samples `SdfDualContouring` reads a normal at
  (`SdfSampledLattice.GradientPoints`): a cell's normal reads its own eight
  corners, so no other sample needs one.
- **A mesh never depends on how its lattices are cut.** A slab keeps its final
  lattice's origin and names its first plane in the lattice's mode word, so its
  samples lie at `origin + (x, y, slab + z) * cell` exactly as the whole
  lattice's would; a slab origin offset by `slab * cell` moves samples by an ulp
  and changes meshes whenever the share changes. `UnionFinal`'s plane limit is
  its own constant (`UnionPlaneSamples`), not the share. Check a change to the
  bake's chunking, scheduling or CPU speed with `puck mesh audit --cpu --group
  <shapes>`: its done line's samples, triangles, vertices and level counts must
  not move. Stages that hold a worker past two seconds log
  `[sdf.mesh-bake] slow … stage=…` with the group and its lattice, and the done
  line's `kinds=` and `cpu=` split samples by stage and summed worker-stage
  elapsed seconds. `Account` uses `Stopwatch`: these totals include descheduling,
  GC suspension and waits inside a stage, not just consumed processor time.
  Read them beside a .NET sample profile and allocation events; queue wall-time
  comparisons through `puck measure request` for the quiet window.

## The library and the store

- **A batch answers the bake that took it.** `SdfMeshBakeBatch.Bake` names it,
  and the slot that dispatched it holds it until its readback is released, so a
  view that leaves the frame or follows another residency never strands a bake:
  no view dispatches or reads back a batch. A slot is reused only after its
  fence signaled and its client released the readback (`SdfGpuWork`, the one
  owner of its slots), and a slot's inputs and outputs (its pass block, point
  table, instance masks and samples) are written only while it is free. What a
  batch reads of the tables is retained through the device timeline. Background
  admission requires the tables' frame queue, so the same checkpoint covers
  frame and batch readers; an upload waits out a lease on the ring slot it
  rewrites (`SdfGpuWork.EndLeases`). A batch
  abandoned (a recording that failed, a disposed service) returns its lattices
  to their groups, which dispatch them again, and counts its samples as
  `returned`, or `discarded` once the GPU sampled them (a failed readback, a
  group retired while its lattice flew: GPU work spent for nothing);
  `Answered` settles a batch once.
- **Readback ownership belongs to a job, never a recycled token.** Every
  completion gets a new `SdfGpuWorkReadback`; its gate serializes reading,
  release and revocation. A stale or concurrent second release cannot free
  the next occupant, and disposal waits for the reader before freeing native
  storage. `SdfWorldTablesWorkLawTests` exercises those interleavings and
  recording, submission, completion and device-loss failures. A throwing
  completion never accepts ownership. Keep a submitted job tracked until its
  timestamps have been read; a failed submission may have executed commands
  without a usable fence, so disposal drains the device before abandoning it.
  `DirectXSubmissionFenceLawTests` drives the actual fence through native
  stand-ins at rollover: renew a drained fence before `UINT64_MAX`, which
  `GetCompletedValue` reserves for device loss, never signal that value or
  wrap to zero.
- **Groups are keyed by geometry** (`SdfMeshGeometryBuilder`: instructions with
  side-table values for offsets, materials by place, instance bounds in their
  declared frame and the bake turn for nonzero world-axis offsets, other slots
  by their rounded pose in the group's frame, lane-erosion
  lanes, the reach of a box it clamps, glass, and for a group holding a glyph the
  content identity of the atlas pixels its glyphs sample, `SdfProgram.GlyphAtlas`,
  which `SdfProgramBuilder.Glyph` takes from the atlas image's
  `FontAtlasImageData.ContentHash` and a retained emission carries, since a glyph's
  instruction holds only its cell's UVs; one texture binds for a program, so the
  builder refuses glyphs of two atlas images; each appended as a kind tag, its
  length and its payload through `AppendFact`, so no two fact sequences hash
  alike), and every meshed group is stored in the
  `SdfMeshLibrary` all of a presentation's residencies share, so a rebuild, a
  returning body or a body crossing from another world takes its mesh; only new
  geometry bakes. The key has two failure modes. A field the hash reads that a
  program assigns by position (a slot, a table offset, a palette index) breaks
  sharing silently: canonicalize it in the builder. Anything the bake samples
  that the instructions do not hold (another slot's transform, a lane, a table)
  leaves a stale mesh drawing after an edit: hash it in the builder. A
  stamp-pool blend group uses rigid delta slots and opts into the authored-rest geometry, so arrival
  poses do not change its key or its form's reference pose. Other dynamic instances retain their
  declared pose semantics. A geometry whose bake found no surface is held as empty
  (`SdfMeshLibrary.StoreEmpty`), so a group of it at another selector finishes at once. The
  library holds every mesh, empty result and form under the identity of the
  bake that made it, and a program keeps a group (`SdfMeshPathBake.Keeps`,
  `Renumbers`) only while that identity stands: after an applied update to the
  bake's code or a reloaded bake kernel, every group bakes again, drawing its
  earlier mesh until the new one lands.
- **A material id shift renumbers every later mesh.** A group whose material
  ids moved takes its mesh renumbered (`SdfMeshLibrary.TryTake`), a new
  `SdfMesh` the mesh region lands again word for word through the background
  work, with its draw held out of the frame until it lands. Program material ids are dense in
  registration order, so a placement that stops or starts showing a palette
  shifts every group after it: a responding static row registers the palette
  of every creation it can show (`WorldPlacementStamper.EmitStatic`,
  `ResponsePaletteLawTests`), and a creation with nothing to draw emits no
  instance, so a response swaps one row's materials alone. A body leaving or
  entering a world adds or drops its palette ahead of every later body's: a
  skinned group of the same form and material count at its slot keeps its
  mesh renumbered (`SdfMeshPathBake.Renumbers`), so the bodies after it bake
  nothing, though they stand off their baked pose (the renumber law in
  `SdfMeshPathBakeLawTests.Rebuild`).
- **A published mesh is what the store answers.** `SdfMeshLibrary.Store` writes the entry and publishes the baked
  mesh in the form a decode of that entry gives (`SdfMeshStoreCodec.Conform`: positions on the entry's grid, unit
  normals through their octahedral words, every other plane exact), without reading the entry back, so a cold bake
  draws the mesh a warm boot loads (`AStoredMeshIsWhatItsEntryAnswersWithoutTheEntryBeingRead`), and every store-published mesh's normals
  and coarser levels' indices can be let go once no region owes its words and restored from the entry when a
  region owes them again (`SdfMesh.Restore.cs`; the residency's store line reads `mesh-releases`, `mesh-restores`,
  `mesh-released-now` and `mesh-restore-misses`). Restores run on at most a quarter of the processors' pool
  items and decode into the blocks outside the storage's gate; any failure, an allocation's included, ends the storage lost. A
  library that publishes from a set pins it (`SdfMeshStore.Hold`, `CacheRetention.HoldSet`: a shared lease
  beside the set that no process's eviction passes) for the rest of its process. The held mesh's palette is
  the first taker's only when later takers can renumber from it (`SdfMeshMaterials.Remap`: the decode reads the entry in the first taker's ids, or in the stored ids when one collides); otherwise
  the store's canonical ids are held. A restore the store cannot answer loses the geometry
  (`SdfMeshLibrary.Lose`): the library forgets it, `LostRevision` moves, and each bake holding the library restarts on
  its program, baking again the groups whose meshes were lost (`Keeps`). A write the store refuses publishes the
  baked mesh, which keeps its parts.
- **The World's library persists across runs** (`SdfMeshStore`, the `meshes`
  device cache). `SdfMeshBakeIdentity` derives keys for sampling, contouring,
  simplification and landing. The final mesh is tried first. On a miss,
  `SdfMeshPathBake.ResumeCheckpoint` looks for the simplified mesh or the
  finished contour, including material cuts and skinning. Both use the
  lossless path in `SdfMeshStoreCodec.EncodeExact`. An earlier miss drives
  contouring normally, and it may reuse individual samples for any unchanged
  lattice or point request. The sample key (`SdfMeshPathBake.SampleInput`, the
  one derivation a probe and a write share) is the dispatch's packed lattice row
  and points over the group's `SampleKeys`, part of its `CheckpointKeys`
  (`KeyCheckpoints`: one immutable set taken from one program, replaced whole),
  which the take records beside each lattice it dispatches, so the reader that
  keeps the samples never reads the live group. A group a new program keeps
  mid-bake (`Place`, `Keeps`) carries on and is keyed again under that program,
  since its sealed geometry, and so its mesh, is the same under either. The keys hold the group's
  sample input (`SampleFieldInput`): its `Shape`,
  which the geometry hashes before the tier and the operands' poses, the
  program's packed field and step scale, its palette and its pose rows. A tier
  changes what a lattice samples only through those rows or the lattice's own
  row, so a detail tier takes its floor's coarse search and final slabs from the
  store when they sample alike. The take decides a probe under the gate from
  identity-sized facts alone: what the store knows of the sampling identity's
  sets (`SdfMeshStore.MayHoldSamples(identity)`: the directory listed once on
  the pool, or found missing, then kept by this process's writes and deletes),
  so a cold store dispatches every lattice in its first take with no file read
  and no hash. A lattice whose identity the store may hold goes to the pool's
  urgent queue (`LoadSamples`), which hashes its points (a request holds up to
  `LatticeTaps`, never hashed under the gate), checks and reads the set, while
  the group stays held (`Contouring`) so no stage moves the points; one that
  misses there dispatches in the next take unprobed. A dispatched
  lattice's samples, its contour and its simplified mesh go to the store's
  writer (`SdfMeshStore.KeepSamples`, `WriteCheckpoint`: a `BoundedWorkQueue`
  of two pool items, drained for up to ten seconds at process exit), never
  ahead of the answer or the landing; past `MostPendingWriteBytes` held, a
  checkpoint writes on its caller and a sample set is not kept
  (`store-writes-dropped` on the residency's store line). Every entry is encoded
  straight into its temporary file and written atomically without a flush to
  stable storage (`AtomicFile.WriteVerifiedCache`): its checksum refuses what a
  power loss leaves. A native checkpoint alone is encoded on its caller into a
  buffer the writer copies out, since its parts may go before the writer runs.
  The finished mesh's write stays on the landing, since a published mesh
  restores its parts from that entry, and returns the position planes it stored
  (`SdfMeshStoreCodec.Encode`), which the published native copy conforms to;
  its bound's enforcement runs on the writer. All products share the store's byte
  budget. The bake's done line prints hit/miss counts for the three intermediate
  stages beside its actual GPU dispatch count.

  The final codec's quantization (the position grid and octahedral normals)
  decides what every later run draws. The
  encoder's fit check, the decode and `Conform` expand quantized positions through `SdfMeshStoreCodec.Expand`,
  so the encoder's budget holds for what the decode writes and what a cold bake publishes. An edit to what a decode
  answers for the two lossy planes changes `Conform` in the same change as the decode. The kernels' source
  closure is `passes/sdf-bake-world.hlsli`: their own interface
  (`isa/sdf-mesh-bake.interface.hlsli`, `SdfWorldInterfaces.MeshBakeParameters`:
  a pass block of `SdfWorldPackage.BakeValues` alone, the masks, samples and
  counters, and the World group with the field's tables first), the field
  interpreter, the field's generated vocabulary (`isa/sdf-isa.hlsli`) and the
  work counters, stamped with the field's fingerprint
  (`SdfIsaFingerprint.Field`). A lighting, screen or view module, a renderer
  constant (`isa/sdf-render.hlsli`), a world pass-block value or resource, or a
  World table after `FieldTables` is outside it and leaves their bytecode byte
  for byte as it was on DXIL and SPIR-V; an edit to the field, its generated
  vocabulary, the encoding or the bake kernels moves it. The code part is read from
  the build's assemblies through the shared `Puck.Assets.CodeClosure` walker;
  `SdfMeshBakeClosure` supplies the bake's roots and transport boundaries, while
  compiled-world chunks and generated machine images use the same walker with their own roots.
  The closure starts from production entry methods. The contour walk stops at
  `SdfMeshPathBake.SimplificationStage.Run` and the simplification walk starts
  there. The sampling walk starts from the batch methods that pack the dispatch inputs. The final closure reaches group/geometry planning, lattice refinement,
  contours, material cuts, skin and levels. It follows every call, delegate, override of a type the bake constructs
  and implementation of an abstract member it calls across the `Puck` assemblies `Puck.SdfVm`
  references, and hashes each method's IL with its tokens written as the
  members they name, its locals, exception regions and loaded field data, and
  each named type's layout. A value type's layout counts whole (the bytes its
  code moves); any other type's counts only the fields the closure's code loads,
  stores or takes the address of, so a field the bake never reads (a
  presentation-only flag on `SdfFrame`) leaves the identity as it was, and a
  record the code merely copies with `with` has its synthesized clone and copy
  constructor hashed by signature (they read no field). A record the bake
  constructs counts its whole layout, since its synthesized equality and
  printing read every field. `SdfMeshBakeClosureLawTests` pins both ways. It
  stops at `SdfMeshLibrary` and `SdfMeshStore`,
  which hold meshes, at a mesh's claims and restorable parts (the stop types `SdfMesh/Payload` and
  `SdfMesh/Restorable`: `CodeClosure` stops a nested type named by its full name), and at `GpuRegion` and
  `GpuUploadRuns`, at memory accounting and storage (`MemoryAccount`, `HostMemory`, the allocators and
  `OwnedBuffer<T>`: admission paces when a group holds its final lattice, never what it meshes, and a buffer holds
  the words the bake's own code writes), at bake admission pacing (`SdfMeshBakeBacklog`), and at the runtime. It also
  stops at `SdfMeshBakeReport`, which words, counts and writes every `[sdf.mesh-bake]` line and owns the counters
  they report (`Accounts`): the bake hands it values (a group's selector, counts, outcomes) and never builds or
  writes text itself, so an edit to a line's words, or a new counter, leaves the identity as it was. A new line or
  counter goes in that type. What the bake stores for a line's later use (a group's `Outcome` text) is still
  its own code. The checkpoint keys also cover their storage format. The final mesh key reads the encoder and its
  quantization. The store decoder and background GPU scheduler can change independently. An edit to `Puck.Maths` code the contour calls moves the contour
  key and its downstream stages. Comments and checkout paths do not
  change the key, and worktrees of one bake share one set. Appearance is outside the key by construction: the
  closure's program root is `SdfProgram`'s only constructor, the field derivation, which takes no material or screen
  value, only an `SdfAppearanceOutline` (material count, glass materials, declared screens, the appearance section's
  size). `SdfProgram.Of` runs it and then attaches the `SdfAppearance` and packs its materials and paints into the
  stream's tail; the program's appearance is unattached while the field constructor runs, so a read of it there throws
  rather than joining the key. The CPU field evaluators the bake runs (the skin's influence round, the audit) read
  `SdfProgram.Excerpt`, which the field constructor derives from the outline alone with no appearance attached, so
  they reach no appearance code either. The kernels follow the same split: the stream is field first (`SdfProgram.FieldWords`),
  the field interpreter finds the bound table at `dataOffset + 2 * instructions`, the material and paint strides and
  lanes live in `sdf-render.hlsli`, and the field fingerprint describes the encoding over `FieldWords` alone (the
  description leaves out a probe input that moves no described word, so a new material input on the probe's material
  call moves only the whole fingerprint). An edit to
  a material's values, a paint, a screen surface or `SdfAppearance`'s code leaves the identity standing (`puck mesh
  identity --against` reports the same identity and kernels); the one material fact beside places that shapes a mesh,
  glass, enters each glass group's geometry (`SdfMeshGeometryBuilder.AppendGlass`). The diagnostic slice, frame/input
  types, admission and settle accounting remain conservatively reached.
  A new member matters if a positive entry or its callgraph reaches it. Code the bake
  reaches only through reflection or a runtime callback on a type it does not
  construct is outside the walk: add a root to `SdfMeshBakeClosure` for it.
  Finish formatting before measuring a new cold set: argument ordering can change IL and therefore
  the computed bake identity even when the source rewrite preserves semantics.
- **Dressing is outside derivation.** Top-level `SdfMeshDresser` owns retained topology, posed draws, clipping,
  pick maps and draw claims. Its constructor binds one bake; dispose it before retiring that bake or its library.
  `SdfMeshPathBake.PrepareFrame` is the one locked door: restart/reconcile the frame, update the single copy-membership
  index shared by demand and dressing, revisit moved frame inputs, prioritize, finish replacements and retier, then
  return a stack-bound `FrameAccess`. Its consumer
  claims the landed meshes and publishes draws/picking before acknowledging that access's captured product revision;
  it reads the groups only while the access holds the gate, and releases it (`FrameAccess.Release`) once its rows claim
  every mesh it draws, so posing, clipping and publishing run with the gate open; a group read after the release throws.
  Disposal releases the gate without acknowledgment. Every mesh replacement, including a same-count or empty result,
  advances the revision. `Stage` chooses and slices the exact point/pose rows; its caller uploads the returned span
  through the generic region transport. No bake entry calls the dresser. This is a type boundary as well as a call
  boundary: applied code updates report types, including declaring types of nested helpers, so a partial/nested dresser
  would still invalidate the bake. `SdfMeshBakeClosure.Reads` includes producing types and excludes the standalone dresser,
  draw history, world tables, pass recorder and the view frame block; unknown applied-code updates remain conservative.
- **A miss names its cause.** Each identity's parts and code members are
  recorded beside the entries (`<identity>.identity`, the 64 most recent kept),
  and a start that bakes groups logs one line: `[sdf.mesh-bake] miss … identity
  … unchanged: geometry new to its set of S entries (N entries in K sets, B of C
  bytes)` or `… unchanged: its set was evicted, or it never stored one (…)`, or
  `identity … new since <earlier>: the code, K members (Puck.Maths
  1: Puck.Maths.VectorFunctions.IsFinite) changed`. `puck mesh identity --build <dir>
  --against <dir>` prints the same comparison for two builds with no boot, and
  its value is the key a cache of the store is saved under.
- **The store keeps whole sets.** Each identity's entries are one set, in a
  directory named for the identity (`SdfMeshStore.SetDirectoryOf`). The debug
  world's set is compressed with its mesh codec; the store keeps `SdfMeshStore.DefaultCapacityBytes`
  (8 GiB), shared by every World and worktree on the machine, a set at a
  time (`CacheRetention.EnforceSetsOnWrite`, which the store's writer runs after
  each entry stands): a set's last use is its most
  recently read or written entry's, and a write removes whole sets, least
  recently used first, keeping its own. A peer's write may evict a set being
  baked or loaded unless it is pinned (`SdfMeshStore.Hold`). An unpinned writer's
  set larger than the cap alone keeps its most recently used entries, including
  the entry being written. An entry left directly in the directory is a set of its own and ages
  out first. A boot that bakes nothing shows `done … loaded=N` with
  `dispatches=0`. A program that arrives while groups are pending and takes
  every group from the library reports the started bake `done` at once
  (`SdfMeshPathBake.Restart`), since no landing follows to report it.
  Any replaced group invalidates the dressed draw list, including a cache hit
  with the same group count: no later bake callback will repair a stale draw.

## Shadows and indirect light

- **Cascades are depth only**: the shadow pipeline
  (`SdfMeshRasterPass.ShadowKey`, `sdf-mesh-shadow.vert`/`.frag`) draws the
  mesh draws into each cascade's sampled `D32Float` depth from the light camera
  `SdfFrameBlock.WriteShadowCamera` writes, with the view cameras' handedness;
  `sdfMeshShadowDepth` in `passes/sdf-surface-stage.hlsli` decodes that
  reversed, linear depth, so the two projections are a sync pair. The shadow
  tier sizes the cascades (`SdfShadowResolution`, `meshShadowTexels`) and a view
  holds the second slot's cascade only while its world holds a second stable
  slot (`SdfWorldPackage.WithShadows`).
- **A view without shadows holds no cascade.** A view whose quality skips
  shadows (windows, camera views) runs `SdfWorldPackage.WithoutShadows` of its
  fragment: the cascades' passes and their 252 MB of targets go, and the
  surface pass binds the filler.
- **Shadow handoffs are pass values.** The outgoing light fades from its slot's
  cascade by the handoff's weight; the incoming light lights unshadowed until
  it holds the slot. No handoff plans or allocates anything.
- **Indirect light is the irradiance volume.** `SdfWorldResidency.IndirectTier`
  (the host lever, else the frame's tier) drives `SdfMeshIrradiance`, staged
  before the upload into the staged World table `sdfMeshIrradiance` and
  described by the pass-block values `meshIrradianceVolume` and
  `meshIrradianceLevels`. The probe layout, key, toroidal slot, normal bias and
  probe weights are a sync pair between `SdfMeshIrradiance` (its CPU feedback
  read included) and `shade/sdf-mesh-irradiance.hlsli`, which only the views
  kernel compiles. The trace reads static mesh draws through
  `SdfMeshIrradianceScene`; never route it through the field interpreter. The
  scene is two-level and keyed by each mesh's position and index buffers, which
  its triangle tests read in place (a geometry holds only its hierarchy and the
  leaf order of its triangles), so a static-draw change builds only geometry new
  to the previous scene: a slow `[sdf.mesh-gi] scene` line with a large
  `built-triangles=` means new geometry, not the trace. `puck mesh scene --world
  <file>` times a build and a one-draw change over the stored meshes with no
  device, and `world.counters sdf.mesh-gi` counts builds. A triangle whose box's
  surface passes 64 times its area, a long thin one a merged polygon leaves,
  enters the hierarchy as up to 64 pieces each boxed tight, every piece naming
  the one triangle: unsplit, the merged debug world's trace took 10.6 CPU seconds
  a sweep where the unmerged took 6.9, and split it takes 7.3, with the same
  hits. The
  [handbook](../../../../docs/rendering/sdf/handbook/lighting-and-shading.md#the-mesh-paths-irradiance-volume)
  owns the technique and its limits.

## Auditing a bake

`puck mesh audit --world <file>` finds bake defects without a GPU or a person
looking: it reads the meshes a World boot stored (`SdfMeshStore`, never writing
it), measures each against its group's own field on the CPU (`SdfMeshAudit`,
through `SdfFieldEvaluator`'s render reading), and prints per group, worst
first, the off-surface error at vertices, centroids and edge midpoints, face and
shading normal error against the field gradient, folds, flips, open edges,
uncovered surface and how loose the field is, then the worst clusters with
rest-pose and author-frame positions, the worst sample's position with the
mesh's facing against the field's gradient there, and the shapes nearest them. The
[CLI reference](../../../../docs/reference/cli.md#puck-mesh-auditbaked-mesh-audit)
owns its flags.

`RestScene.Compose` reconciles its `WorldTextCatalog` before emitting the frame. A catalog object
without that call silently omits text and makes the audit miss every glyph group, even when the
definition carries prepared font assets. Keep this offline scene path aligned with the live emitter.

- **Run it before calling a bake or mesh-path change done**, and on a changed
  creation's groups (`--prototype`, `--group <shape>`); a later run over the
  same store proves a fix. `--images <dir>` draws each worst cluster on the
  CPU, shading beside face normals: the offline twin of
  `world.debug-view normals`.
- **A defect's class and its refinement flag are in the report.** Each flipped
  triangle, fold, off-surface vertex, open or non-manifold edge and uncovered
  crossing is sorted by geometry into `SdfMeshDefectClass` (`crease-sliver`,
  `narrow-face`, `off-surface-vertex`, `short-tip`, `other`), and with `--cpu`
  each is read through the group's `SdfRefinementMap` (what `SdfSampledLattice.Refine`
  flagged, `SdfMeshPathBake.RefinementObserver`) into `measured`, `ring`,
  `unflagged` or `lattice-unrefined`. Run it on a defect before deciding whether
  the fault is the trigger (items `unflagged`) or the contour (items `measured`
  or `ring`). The class is the geometry's reading, not the bake's cause.
- **`--cpu` measures a bake change with no GPU.** It drives `SdfMeshPathBake`
  with each lattice answered through the group's CPU field, so a contour,
  refinement or field change shows in the audit without a boot. Every lattice
  names where its gradient taps lie (`SdfMeshBakeRequest.TapSpacing`, a
  sixty-fourth of its finest cell); the kernel reads that spacing from the
  lattice's record and the CPU answers it too, so neither side decides it
  alone. The fixed-point evaluator answers in 2⁻¹⁶ m steps and cannot place
  taps closer than `SdfMeshCpuField.ResolutionSpacing`
  (`SdfMeshCpuField.TapSpacing`): there its taps straddle creases the
  kernel's do not, and the group's block prints a `cpu taps:` line counting
  those samples. Only a group without that line, and whose field the two
  interpreters compute alike, has a CPU mesh that should match a stored
  bake triangle for triangle. Read the others' folds and flips beside a store
  audit: blended crease normals can hide folds the device's one-sided normals
  produce, and can add flips the device does not have.
  A field the evaluator refuses (a regular polygon, a glyph, a sampled
  region) needs a World boot.
- **The store is keyed by the bake identity of the build that booted.** From
  your own worktree's CLI, audit a World you ran from the same checkout, or name
  another build with `--build <its Puck.World bin dir>`; a rebuilt build's
  meshes stay readable under the `--identity` an earlier report printed.
  `--history --group <shape>` compares every build's stored bake of one
  geometry. `--backend` names the backend that baked (Direct3D 12 by default).
- **The audit reads stored meshes against the CPU field; `world.slice` reads
  the live field.** Use the slice to see what the GPU walk answers on a plane,
  the audit to see what the bake made of it.
- **Read the metrics together.** Sawtooth edges show as face normals off the
  gradient and folds strung along an edge; torn or dropped walls as uncovered
  crossings and open edges; a cutter that is only a lower bound (a stretched
  ellipsoid, a non-uniform `Scale`, a flare) as a slope deficit, attributed to
  the shape whose own field is loosest there.
- **`rough` sees mottling the centroid checks cannot.** The shading check
  compares each corner against the gradient at its triangle's centroid, which
  the surface's own curvature over half a cell turns by up to the 30-degree
  threshold, so sub-cell relief of 5 to 15 degrees scored clean. `rough`
  measures each smooth vertex (copies with one normal; crease copies stay with
  the shading check) against the gradient at the vertex across a quarter cell,
  where a correct bake's normal is the gradient, and flags past 10 degrees. A
  CPU field that rounds a product of two lengths before dividing (a superellipsoid
  ratio `(|p| · min(r)) / r` rounded at the product craters every ellipsoid and
  sphere at centimetre sizes in `MeshCpuBake` and `mesh preview`) reads p50 near
  10 degrees; a sound one reads under 1. A loose bound multiplies the CPU twin's
  rounding by its slope deficit: a flare raises `rough` p99 to about 6 degrees
  on every primitive in a CPU bake, which the kernel's float field does not.
- **Audit changed collapse levels explicitly.** `--level 1` and `--level 2`
  select the triangles those forced render levels draw, clamped per chunk to
  its last level. Only referenced vertices count. The field coverage lattice
  and error thresholds retain level zero's bounds and cell; a coarser mesh
  must not buy a cleaner report by enlarging its error budget. `--images`
  draws the selected level too. The default still audits level zero.
- **`--cpu --field-levels` measures field levels that follow the collapse.**
  `SdfMeshFieldLevels.Contour` drives `SdfMeshPathBake.ContourLevel` (the
  bake's own lattice, refinement, crossings, contour, field check, crease
  split, material cut and planar merge on a coarser lattice at an outward
  iso-value), coarsest first and down to the first level past the kept share
  of the collapse's coarsest, flattening near-coplanar faces first
  (`SdfMeshPlanarMerge.Flatten`: the field level's gradient normals differ in
  their last bits, which the exact merge reads as separate faces) and
  vanishing components that would flip or open an edge past level zero's
  count. `SdfMeshFieldLevels.Measure` is the one place the plan's error
  contract is computed, for field and collapse levels alike; a vanished
  part's level-zero surface counts by its run's extent and is excused from
  enclosure and from the audit's missing crossings (`SdfMeshAudit.Audit`'s
  accounted surface). Flattening recovers little on an offset level: an
  outward offset rounds every edge into a strip no planar merge takes. The answers go through `ISdfMeshLevelField`, which the CLI
  implements on `MeshCpuBake`'s sampler and the shared tap stencil
  (`SdfMeshBakeTaps`), counting evaluations by contour and oracle and the
  thread work inside them (`ThreadCycles`). A field whose level-zero brackets
  break its step scale (`SdfMeshFieldLevels.Certified`) is answered at every
  sample; a member's part takes its own box, and a slot whose shapes only carve
  is no part (`SdfMeshAudit.MemberFields`). The offline bake answers the skin
  round with each lattice's own slot, so no CPU-baked group is skinned and every
  multi-slot group carries collapse levels a World's bake would not give it.
- **What it cannot read.** The render reading interprets every warp, fold and
  relief the renderer draws, a non-uniform scale, a sweep of any strand count
  and a path's edge table, each a sync pair with its `mapCore` case
  (`SdfFieldEvaluator.RenderOps.cs`, `SdfFieldEvaluator.Path.cs`); a group
  holding a regular polygon or star (runtime trigonometry), a glyph or a
  sampled region reports `field refused`, and one whose evaluation faults
  `field failed`. Mirrored groups (left and right) share one geometry and one
  stored mesh.

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