@woosh/meep-engine 3.14.6 → 3.15.0

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_LEDGER.md

@@ -0,0 +1,463 @@
+# AVBOIT — ledger
+
+Companion to [`AVBOIT_PLAN_2026_09_03.md`](./AVBOIT_PLAN_2026_09_03.md). One entry per step of §8, in the
+order they landed, each recording what was built, how it was verified, and what the step found that the plan
+did not predict. Findings that change the plan are noted here and the plan's revision header is bumped, never
+silently edited.
+
+Branch: `claude/avboit-transparency-pipeline-192cff`, worktree
+`.claude/worktrees/avboit-transparency-pipeline-192cff`, from `9ab84a154`.
+
+---
+
+## 0. Survey — 2026-09-03
+
+**Done.** Read the deck (text extraction via `pdftotext`; the page renderer is not installed here) and the
+MBOIT pipeline end to end: orchestrator, three shaders, frame-graph API, resource descriptors, the bucket →
+draw-command prep, the emulator's capabilities, the software device's recording API, and the `Renderer` call
+site and mode-switch precedents.
+
+**Findings that shaped the plan:**
+
+- The sorted meshlet buffer the draws consume has no count header
+  (`shader_sort_meshlets_by_material.js:20` writes a bare `array<MeshletDefinition>`); the collection *before*
+  sorting does, and the prep helper already builds an indirect dispatch command over it. The occupancy pass
+  needs both, so the helper returns two more handles (plan §3.1).
+- No render pipeline in the tree writes a storage buffer from the fragment stage, and the pipeline-layout
+  helper applies one visibility to all groups. The splat pass builds its layout per group (plan §3.11).
+- The emulator models `atomic<T>` as `{ value }` objects and implements `atomicAdd/Min/Max/Or`, `textureStore`
+  on 3D `CPUBitmapData`, `extractBits/insertBits`, `countOneBits`; barriers are no-ops and there is no
+  workgroup-cooperative dispatch. The warp build is therefore a single invocation so it stays
+  emulator-testable (plan §3.4).
+- View-space depth sign: the volumetrics take `-(view_matrix × p).z`, so the camera looks down −Z; the
+  occupancy pass uses the same (plan §3.3).
+- `float32-blendable` is on the device floor purely for MBOIT's `r32float`/`rgba32float` targets; AVBOIT
+  blends `rgba16float` only (plan §3.11).
+- The in-app browser pane cannot run the full renderer (immediate data unsupported there, per memory), so the
+  playground look (step 9) needs a real Chrome tab; module compilation (step 8) works in either.
+
+---
+
+## 1. Skeleton and switch — 2026-09-03
+
+**Done.** `ShadeTransparencyMode` (`MBOIT = 0`, `AVBOIT = 1`), `Renderer.transparency_mode` defaulting to
+MBOIT, a ternary at the single transparency call site selecting the recorder, and
+`graph_prepare_meshlet_draw_commands_by_material` returning `meshlet_collection` and
+`meshlet_iterator_command` beside what it returned before. `Renderer.js` and the prep helper are CRLF files;
+edited byte-exactly.
+
+**Verified.** The rasterize spec tree (14 files, 81 tests) passes with the helper change; the source-level spec
+in `graph_rasterize_meshes_transparent_avboit.spec.js` pins the import, the default and the ternary.
+
+**Found.** Nothing the plan did not predict.
+
+---
+
+## 2. Depth curve, packing, warp — 2026-09-03
+
+**Done.** `chunk_avboit_depth_curve` (t(z), z(t)), `chunk_avboit_pack` (10|10|10, counts ↔ extinction ↔
+transmittance, the overflow predicate), `AVBOIT_WARP_STRUCT`, `chunk_avboit_warp` (φ, and the view-depth →
+virtual → physical composition), each with an emulator spec.
+
+**Found.**
+
+- The emulator hands a `u32` with its top bit set back as a negative JS number (`0xFFFFFF00` reads as
+  `-256`). Specs compare through `>>> 0`. `countOneBits` and the shift operators are unsigned internally, so
+  the shaders themselves are unaffected.
+- `vec3<f32>` values travel as `Float32Array` through the emulator, so round-trip expectations are f32-exact
+  (six digits), not f64.
+
+---
+
+## 3. Occupancy and warp build — 2026-09-03
+
+**Done.** `chunk_avboit_occupancy` (range, word mask, dilate, fold), `shader_avboit_occupancy` (per meshlet,
+indirect over the filtered collection), `shader_avboit_build_warp` (one invocation: dilate → count → halve
+until it fits, then the exclusive-prefix LUT), with specs for the chunk and for the whole build shader
+dispatched through the emulator.
+
+**Found.** The implementation dilates at *every* level it evaluates rather than once at the finest and once at
+the settled level, which is the same thing where it matters (the settled level) and simpler to reason about.
+`AVBOIT_OCCUPANCY_DILATION` at the prepass is therefore only a belt-and-braces one slice. Plan §3.4 describes
+the per-level version.
+
+Specs pin: empty → `V_max` and an all-zero LUT; a run that dilates to exactly `P` does not halve; one over
+halves once and is re-dilated at the coarser level; everywhere-occupied halves down to `V = P`; the prefix is
+exclusive, monotone, and never exceeds `P`.
+
+---
+
+## 4. Splat — 2026-09-03
+
+**Done.** `shader_avboit_splat`: low-resolution render pass, no depth attachment, a `r8unorm` dummy target
+with `writeMask: 0`, per-group pipeline layout with the atomics group fragment-only, linear splat with
+per-channel overflow marks stored inverted under `atomicMax`. `chunk_avboit_tint` factored out so the splat
+and the draw compute the transmission tint from one function.
+
+**Found.** No un-jitter in the splat: `unjitter_uv` is derivative-based and the jitter is in
+internal-resolution pixels, so at 1/8 resolution the correction would be eight times too large. Recorded in
+the shader's docblock; the plan did not mention it.
+
+**Verified.** Validity tier (vertex + fragment) and the tier-3 layout spec: group 3 entries are `FRAGMENT`
+with `buffer.type === "storage"`, groups 0–2 are `VERTEX | FRAGMENT`, the target's `writeMask` is 0, no
+`depthStencil`.
+
+---
+
+## 5. Integrate — 2026-09-03
+
+**Done.** `shader_avboit_integrate`, 8×8 workgroups, exclusive prefix into a `P + 1`-deep `rgba8unorm` 3D
+storage texture, per-channel saturation and overflow pinning. Emulator spec over one column: exclusive
+prefix, independent channels, saturation, a summed field past 255 saturating in one step, an overflow mark
+pinning only its channel, a mark at slice 0.
+
+**Found.** Nothing unpredicted.
+
+---
+
+## 6. Draw and sample — 2026-09-03
+
+**Done.** `chunk_avboit_sample_transmittance` (bias in virtual slices, warp, `(p + 0.5) / (P + 1)` depth
+coordinate, `exp`), `avboit_draw_fragment_body` (one WGSL text shared by the IBL and Brick4 pipelines, where
+the two MBOIT resolve shaders share theirs by duplication), `shader_avboit_draw_ibl`,
+`shader_avboit_draw_brick4`, `AVBOIT_INTEGRAL_SAMPLER_DESCRIPTOR`. Emulator spec of the sample chunk against a
+hand-built integral: run boundaries land on texel centres, an event in front attenuates by `exp(-E × ln 256)`,
+the bias clears a surface's own linear splat, a gap sample reads the previous run's total and none of the
+next run's, beyond the far plane the sample reads the total.
+
+**Found.** The emulator's `null` sampler is the linear clamp-to-edge fallback the spec wants, so no sampler
+object is built there.
+
+---
+
+## 7. Resolve, orchestrator, tier 3 — 2026-09-03
+
+**Done.** `shader_avboit_resolve` (reads the scene, writes a fresh `rgba16float`; RGB total transmittance
+cannot blend in place), the full `graph_rasterize_meshes_transparent_avboit` with its sub-recorders exported
+(`graph_avboit_occupancy`, `_build_warp`, `_splat`, `_integrate`, `_draw`),
+`avboit_shaders_wgsl_validity.spec.js` (10 modules, zero diagnostics),
+`graph_rasterize_meshes_transparent_avboit.spec.js` on the software device.
+
+**Found.**
+
+- `graph_compute_pass` cannot create a `read_write` storage buffer from a descriptor: the helper puts every
+  readable binding through the read path first, so the descriptor arrives at `pass.write` as an object. The
+  warp build is recorded by hand instead, and its `settings` uniform is serialized with
+  `encoder.allocateTransientValueBuffer` — the plain-object convenience only exists inside the graph
+  helpers, not in `ComputeShader.dispatch`. Plan §3.1's table is unchanged; the pass is the same, just not
+  via the helper.
+- No spec builds a `GPUViewContext` over a scene on the mock, so the tier-3 spec pins the exported
+  sub-recorders (warp build: one workgroup into a buffer of the struct's size; integration: the dispatch
+  covers the voxel grid and the texture is `3d`, `P + 1` deep, storage + sampled; resolve: one 3-vertex draw
+  into a fresh target) and the `Renderer` switch at source level. The whole orchestrator's first encode is on
+  a real device (steps 8–9).
+
+**Verified.** 62 tests across the avboit directory; 81 across `rasterize/`; the full `src/shade` suite
+(489 files, 3360 tests) passes; `scripts/check-types.mjs` reports the declaration emit clean and zero
+consumer-visible errors.
+
+---
+
+## 8–9. Real compile and the look — 2026-09-03, handed over
+
+**Done.** `src/shade/playground/avboit/`: the deck's harness in miniature (a stack of cards at a controlled
+spacing, a tinted glass pane, an opaque backdrop), the MBOIT/AVBOIT switch, and a **Compile check** that
+pushes all ten AVBOIT modules through `createShaderModule` on the live device and prints
+`getCompilationInfo`. The README carries the one scripted session (six steps) with what "pass" looks like
+for each.
+
+**Not done here, and why.** The in-app browser pane returned `null` from `requestAdapter()` this session
+(its `wgslLanguageFeatures` are present, the adapter is not — the same state
+`playground-needs-immediate-data` recorded on 2026-09-02), and no Claude-in-Chrome browser was connected.
+So neither the real compile nor the picture happened on this side. What the pane did prove: the page
+loads under the dev server, every import resolves (the ten shader modules assemble at import time, so a
+chunk-dependency or struct error would have thrown there), and `start()` runs up to
+`Renderer.initialize`, which reports `requestAdapter returned null` cleanly. The sources were dumped
+(`scratchpad/wgsl/*.wgsl`, 217 KB) for a pane compile should an adapter come back. What is known: every
+module passes the validator, which has no type checker; the type-level risks are listed below so the first
+compile failure, if any, is quick to place.
+
+**Type-level things the validator could not see** (in the order a compiler would meet them):
+
+- `avboit_warp` takes `ptr<storage, AVBOITWarp, read>`; the splat and draw pass `&warp` where `warp` is
+  declared through `addStorageBuffer(..., false)`. `var<storage>` without an explicit mode is `read`, which
+  matches.
+- `atomicAdd(&extinction_volume[column + u32(s)], …)` indexes an `array<atomic<u32>>` binding from the
+  fragment stage — core WGSL, but the first such pipeline in the tree.
+- `textureStore(integral, vec3<i32>, vec4<f32>)` on `texture_storage_3d<rgba8unorm, write>`.
+- `select(vec3<u32>, vec3<u32>, vec3<bool>)` and `select(vec3<f32>, vec3<f32>, vec3<bool>)` in the
+  integration; both are the component-wise overload.
+- The splat fragment entry has no return type against a pipeline with one colour target at `writeMask: 0`.
+
+---
+
+## 10. Docs — 2026-09-03
+
+**Done.** `RENDERER_CONTRACT.md` §2 says which mode needs `float32-blendable`; §9 lists
+`transparency_mode`. `CHANGELOG.md` carries the entry under the unreleased 4.0.0 "Added". The plan is at
+revision 1; nothing in steps 1–9 required a revision of its design sections.
+
+**Open, for the session in the playground README:** the ten real compiles; the first frame under AVBOIT;
+the stack at the default spacing (does the bar behind it show through?); the spacing at which the cards
+fall into one slice; the red pane's tint on the backdrop. Results go here as entry 11.
+
+---
+
+## 11. Path-traced reference on the playground — 2026-09-03
+
+**Done.** A third mode on the page, "path traced (reference)": `feature_path_tracing_enabled` on, TAA
+forced off while it is, the tracer's running-mean floor lowered from 0.01 to 0.002 so the image keeps
+settling past 100 samples, a **Reset accumulation** button, and a once-a-second readout of how converged
+the image is. That readout needed one small engine addition: `AccumulatingPathTracer.min_sample_count`,
+the sample count of the tile that has had the fewest (the per-tile counters were private, and frames
+elapsed is not a sample count — a frame advances one tile).
+
+**What the reference is good for, and not** (README "The reference"):
+
+- The tracer rolls each transparent hit against alpha and continues the ray, so it converges to the
+  exact order-independent composite of the card stack — the thing both OIT modes approximate. Good.
+- It has no per-channel transmission tint (thin-walled transmission carries only `(1 - F)`), so it
+  cannot confirm AVBOIT's glass tint; the pane is compared with the tint off.
+- Its shadow rays treat geometry as opaque (the tracer's own `TODO`), so the cards cast full shadows
+  there and none under either OIT mode. The stack, not its shadow, is the comparison.
+
+**Verified.** `path_tracer/` has no specs of its own; the getter is a read of a private array. The
+page's module graph was re-loaded in the pane (see entry 8–9 for what the pane can and cannot prove).
+
+---
+
+## 12. First renders on a real device — 2026-09-03
+
+Alex ran the playground and pasted three canvas captures at the default settings (four cards, alpha
+0.85, spacing 1.5, red glass pane): path traced, AVBOIT, MBOIT. Read against the code, not measured.
+
+**The stack — the deck's depth-complexity claim reproduces.** Under MBOIT the green card, two layers
+back, shows through both the red and the blue card as a lighter rectangle inside the red one. Under
+the path tracer and under AVBOIT it does not; the overlap is red with the blue card directly behind
+faintly visible. AVBOIT is the closer of the two to the reference on the stack. Both rasterized modes
+render the cards darker than the tracer, and they agree with each other, so that is a forward-shading
+versus tracer difference and not this pipeline's.
+
+**Also as predicted:** the tracer casts full shadows from the cards (its occlusion query treats
+geometry as opaque), neither OIT mode does.
+
+**The glass pane — the tint is working as written, and is the wrong default.** Under AVBOIT the pane
+is deep red; under the tracer and MBOIT it is clear glass. The material is transmission 1 with a red
+base colour, and `chunk_avboit_tint` multiplies transmitted light by that base colour, so green and
+blue drop to ~14 %. It is not opaque — the horizon shows through as the dark-to-bright step at floor
+level — but it is a material semantic the other paths do not have: the forward shader states there is
+no per-channel transmission tint in the material model, and the tracer's thin-walled transmission
+carries only the Fresnel split. The contract's promise that the two modes take the same inputs and
+are safe to flip per frame does not survive a flip that recolours glass.
+
+Two corrections to what the code says about itself: the chunk docblock calls base-colour-as-tint
+"the OpenPBR default", which it is not (OpenPBR's transmission colour defaults to white; glTF's
+transmission extension is the one that uses the base colour); and plan §4's first row rests on the
+same reading.
+
+**Proposed:** keep the RGB plumbing, default the tint off, expose it as a runtime switch
+(`renderer.avboit.transmission_tint_from_base_color`, carried in the warp header so the splat and
+draw agree per frame), a checkbox on the page, plan to revision 2. The alternative — keep it on and
+document it as an AVBOIT-only semantic — makes one asset mean two things depending on a renderer
+switch. Alex chose the first; entry 14.
+
+**Also closed by these renders:** step 8's real compile, for the IBL variant. An AVBOIT frame on a real
+device means the occupancy, warp, splat, integrate, IBL draw and resolve modules all compiled and the
+pipeline ran end to end. The Brick4 draw variant is not exercised by the page (`indirect_lighting_mode`
+is IBL there) and remains compiled only by the validator.
+
+---
+
+## 13. The deck's opaque-card case on the page — 2026-09-03
+
+**Done.** At Alex's request: a small pale quad, alpha 1 on a `Transparent` material, one unit behind
+the last card and offset so part of it is seen through the stack and part stands against the backdrop
+and the dark bar. Both pipelines clamp its coverage at `OIT_COVERAGE_MAX` (0.997), so it is the "0 %
+transmittance card" of deck slides 35–38: the case where a moment reconstruction cannot hold the
+step, leaks the background through the surface, and tears along the depth discontinuity at its edge.
+A checkbox (`opaque_quad`, default on) and step 8 of the README's session.
+
+**What to expect from AVBOIT here, from the design:** the quad's extinction saturates its slice
+(`-ln(1 - 0.997) / ln 256 ≈ 1.05`, clamped to 1.0), so the integral behind it reads 1.0 and every
+fragment further back is weighted by a transmittance of 1/256. Its edge is a step in the extinction
+volume at 1/8 resolution, softened by the draw's trilinear sample over about one voxel — so a slight
+halo of that width is the expected artefact, not a leak. Anything behind the quad showing through its
+interior would be a finding.
+
+---
+
+## 14. The tint, kept and off by default — 2026-09-03
+
+**Done.** `AVBOITSettings` on `Renderer.avboit` with one switch, `transmission_tint_from_base_color`
+(default false). The orchestrator takes `avboit` beside its other inputs (the MBOIT one ignores it), the
+warp build copies it into a new `tint_from_base_color` header word, and both the splat and the draw
+weight `chunk_avboit_tint` by `transmission_factor × f32(warp.tint_from_base_color)`. The chunk's
+docblock now says whose semantics the mapping is (glTF's, not OpenPBR's). Plan to revision 2 (§3.5,
+§4, §7). Contract §9 lists `avboit`. The page has a checkbox for it, off by default, and step 6 of the
+session turns it on before comparing the pane.
+
+**Why a header word and not a shader constant:** the splat and the draw must agree within a frame, and
+the header is already the one place both read per-frame facts from; a runtime flag lets the page do
+the A/B without a rebuild.
+
+**Verified.** Build-warp emulator spec asserts the header copies the flag; validity tier over the
+edited modules; rasterize spec tree.
+
+---
+
+## 15. Decisions on the open items — 2026-09-03
+
+Alex's answers to the open list, and what each became.
+
+**Slice floor — mine to call; 5 cm is a spacing worth resolving.** Virtual slice thickness is
+`(z0 + z - near) · ln(1 + (far - near) / z0) / V`. At the page's camera (`near 0.1`, `far 200`,
+`z0 = 0.8`) and `V = 1024` that was 5.8 cm at 10 m: one slice, under the two-slice bias, so 5 cm
+blended. `AVBOIT_VIRTUAL_SLICES_MAX` is now 4096 — 1.5 cm at 10 m, 2.8 cm at 20 m, 7 cm at 50 m — so
+5 cm resolves out to about 17 m before the bias eats it, and the adaptive halving still pulls it back
+when more than 128 slices are occupied. The bias stays at 2.0 rather than dropping to the analytic
+1.5: the half-slice margin is what covers the depth difference between a splat fragment (a
+1/8-resolution pixel centre) and a draw fragment on a sloped surface. Cost: 128 occupancy words, a
+16 KB LUT, a longer single-lane loop in the warp build. Specs unchanged in intent (they read the
+constant) and green.
+
+**The opaque quad — fine as is.** Stays on the page.
+
+**Camera.** `OrbitalCameraController` on the page (drag, wheel, right-drag), **Copy camera** to the
+clipboard and a box, **Apply camera** from the box, `camera_state()` / `apply_camera()` /
+`configure({ camera })` from the console. Plan §9 gains the slope risk in its own words: a splat
+fragment carries its low-resolution pixel centre's depth, and on a grazing surface that can exceed
+the bias.
+
+**Brick4 — should land.** The variant exists and is validator-clean; the page now has an
+indirect-lighting select (IBL / Brick4) so the Brick4 draw pipeline compiles and draws on a device.
+The scene has no probes, so the indirect term is black either way; the step is in the session.
+
+**Timings — hook up the profiler.** Done as on `volumetrics_froxel`: **Profile** starts a
+`GPUProfileSession` at `WORKLOAD`, pressing it again drains and downloads
+`avboit-<mode>-<timestamp>.sgpt` for the gpu-inspector-tool, with the mode and the page's settings in
+the note and the adapter in the meta. Same settings, two recordings, one per mode, is the comparison.
+
+**Software device — wrong tool for an end-to-end spec, and that is fine.** Plan §6 tier 3 now says
+so; the full-orchestrator spec is off the list.
+
+**Phase 2 — only clean, unambiguous, non-situational.** Decided item by item in plan §7 revision 3.
+One landed: the draw discards a fragment the volume already calls extinct (`T ≤ 1/256` in every
+channel) *before* forward shading. No new resource or pass; the error is bounded by `1/256` of the
+background (`AVBOIT_EXTINCT_TRANSMITTANCE`), below the 8-bit volume's own resolution. Tile skipping
+(no: sub-millisecond passes), the zero-transmittance depth cull (not now: situational, touches the
+depth other passes read, wants its own plan and a scene that needs it), the monochrome buffer (no:
+two representations for content we do not have), the sparse texture (no: speculative).
+
+**Back-sided materials — ignored for now.** Plan §7 keeps the note.
+
+**AVBOIT is the default.** `Renderer.transparency_mode = ShadeTransparencyMode.AVBOIT`; the enum,
+the contract (§2 keeps `float32-blendable` on the floor while MBOIT is selectable; §9 row), the
+changelog and the page's default select follow. The source-level spec pins the new default.
+
+**Committed** on the branch after this entry.
+
+---
+
+## 16. The page's camera and profile buttons, reported not working — 2026-09-03
+
+Alex: the camera could not be moved, and **Profile** appeared to do nothing with no way to stop it.
+
+**What was verified here.** The page was restructured so the camera, its controller and every control
+are wired *before* the device is requested. That made the input path testable in the in-app pane,
+which has no adapter: a synthetic pointer drag dispatched on the canvas orbited the camera from
+`(0, 2.5, 12)` to `(-7.3, 3.7, 9.4)` and a wheel event zoomed it, read back through `camera_state()`.
+So `OrbitalCameraController` on `document.body`, the pointer device and the transform write are
+correct as wired. What could not be reproduced is the failure in a real session.
+
+**What the restructure found.** Building geometry before `Renderer.initialize` threw
+`Cannot read properties of undefined (reading 'exports')`: the meshlet builder runs on a WASM
+instance (`MeshoptClusterizer`) that instantiates asynchronously at import, and the renderer's own
+initialization had been what gave it time. The page now awaits `MeshoptClusterizer.ready` itself. Not
+the reported fault (the committed order built geometry after the device), but the same class of
+thing: a step that silently depended on another step's timing.
+
+**Made robust, since the fault could not be seen.** Every control handler runs through a guard that
+puts a failure into the report panel (`<what> failed: <message>`) instead of only the console; the
+final settings application is guarded so a settings error cannot stop the frame loop from starting;
+the Profile button carries a `recording` state (label and red border) so a running capture is
+unmistakable and the same button stops it; the controls are spelled out under the canvas. If a real
+session still does not orbit, the report panel now says why.
+
+**Suspicion, unverified.** With HMR off, a reload taken while the page's files were being rewritten
+on disk can pair one version of `index.html` with another of `main.js` or `Renderer.js`; a
+`TypeError` in the settings step then killed `start()` before the frame loop, which is the one
+sequence that leaves the buttons registered, the camera frozen and no picture of the cause. A hard
+reload after this commit is the first thing to try.
+
+---
+
+## 17. First timings — 2026-09-03
+
+Alex ran a short profiling session on the page (the deck's harness in miniature: four cards, the
+glass pane, the opaque quad, 1280x720): **AVBOIT 289.9 us, MBOIT 282.4 us**, averages of the
+transparency work, which he reads as within the noise. Device and capture files not recorded here.
+
+**What that says.** On this scene the two pipelines cost the same. That is the expected shape, not a
+surprise: the deck's cost argument (AVBOIT approaching no-OIT, slides 106-110) comes from VFX content
+with tens of millions of overdrawn transparent pixels, where the 1/8-resolution splat, the saturated
+integral and the early-out remove most of the shading work. Six quads at 720p have almost nothing
+for those to remove, and AVBOIT's fixed costs — the occupancy pass, the warp build, the integration
+over a 160x90x129 volume, the resolve into a fresh target — are of the same order as MBOIT's two
+full-resolution passes over the same few quads. So the number closes the question "does the new path
+cost more on light content" (no), and leaves open the one the deck actually answers, which needs a
+scene with real transparent overdraw. Plan §9's contention risk is unmeasured until then.
+
+**Committed** with this entry.
+
+---
+
+## 18. Review against the engine — 2026-09-03
+
+Alex asked three questions of the code: is anything reinvented, does it follow one function per
+chunk, does it fight the engine. Surveyed and fixed; plan to revision 4.
+
+**Reinvented, now reused.**
+
+- *The depth curve.* `chunk_avboit_depth_curve` (t(z), z(t), a `z0` knob) was a second copy of what the
+  light clusters and the froxels already use: `cluster_depth_to_z_slice` with parameters from
+  `build_light_cluster_parameters`. That builder's `scale` argument is the linearization the deck
+  describes; `avboit_build_depth_curve` chooses it so the curve is pure log from the near offset,
+  because the warp makes near precision free. Gone: the chunk, its inverse, its spec, the
+  `AVBOIT_DEPTH_CURVE_LINEARIZATION` constant, and the camera binding of the warp build (the curve now
+  arrives as three floats in the settings and in the occupancy pass's own settings uniform).
+- *The bit fold.* `avboit_fold_pairs` is the OR of the even bits compacted and the odd bits compacted,
+  which is `decode32_morton2`'s job. Found on the way: for a 32-bit code that function's `.y` is *not*
+  the odd bits — the `<< 31` that separates them in the 16-bit variant (`<< 15`) cannot work in 32
+  bits — and the first reuse trusted it; the warp-build spec caught it as an occupied count of 70
+  against 66. The fold now goes through the correct `.x` half twice, once on `x >> 1`, and has a spec
+  against a bit-by-bit reference. `decode32_morton2` is used nowhere else in the tree; its `.y` is a
+  latent engine defect, noted for whoever reaches for it next.
+- *The sampler.* `AVBOIT_INTEGRAL_SAMPLER_DESCRIPTOR` duplicated `SAMPLER_LINEAR_UPSCALE` (linear,
+  clamped on every axis), which the draw already binds as `sLinear` for the split-sum LUT. The integral
+  samples through that; one binding fewer in the view group.
+- *The draw loop.* `material_draw` existed privately in both orchestrators. It is
+  `rasterize/native/material_draw_indirect.js` now, with the material bind-group layout it needs,
+  imported by both.
+
+**Convention.** 650 of the engine's ~700 chunk files hold exactly one function named after the file;
+mine held two to six. Five chunks became seventeen (`chunk_avboit_pack_counts`, `_unpack_counts`,
+`_transmittance_to_extinction`, `_extinction_to_transmittance`, `_extinction_to_counts`,
+`_counts_to_extinction`, `_overflows`, `_occupancy_range`, `_occupancy_word_mask`, `_dilate_word`,
+`_fold_pairs`, `_warp`, `_view_depth_to_virtual`, `_view_depth_to_physical`,
+`_integral_depth_coordinate`, `_sample_transmittance`, `_transmission_tint`), each with its spec; the
+hand-built warp and the curve's inverse the specs share live in `avboit_spec_support.js`, test-only.
+
+**Kept, on purpose.** `avboit_draw_fragment_body.js` shares one WGSL text between the IBL and Brick4
+draw pipelines where MBOIT duplicates its resolve body. No precedent either way in the tree; two
+45-line bodies drifting apart is the worse failure, and the two files stay concrete modules with no
+conditionals in them.
+
+**Also checked and found conforming:** the manual frame-graph passes match the MBOIT orchestrator's
+shape; `AVBOITSettings` on `Renderer.avboit` matches the other sub-object settings; the settings
+structs defined beside their shaders match `shader_read_out_bucket`; the bit packing uses WGSL's
+`insertBits`/`extractBits` directly, which is what the engine's `bitfield_*` chunks are thin proxies
+for; no `safe_*` math helper was reinvented — the one floor (`max(T, 1e-6)` before a log) has no
+counterpart in `shader/chunk/math/`.
+
+**Verified.** Every spec in `rasterize/` (the avboit directory's now-larger set, MBOIT's, the shared
+bucket code) and the type check.