[Renderer] Build virtualized meshlet geometry with automatic LOD and streaming

[proggeramlug]

Parent: #126
Depends on: #28, #27, #130, and #136

Problem

Traditional per-mesh LOD swaps and CPU submission cannot provide film-scale source geometry with stable frame cost. #28 and #27 establish GPU-visible geometry and visibility shading, but Bloom still needs an offline/runtime virtualized-geometry system to approach Nanite-class density.

Outcome

A Nanite-inspired, not Nanite-identical static-geometry path:

• imported meshes are partitioned into meshlets/clusters with bounds and error metrics;
• clusters form a hierarchical LOD DAG/tree produced by the cooker;
• GPU culling selects clusters by frustum, backface cone, projected error, and Hi-Z occlusion;
• indirect draws/visibility IDs render selected resident clusters;
• required pages stream under a fixed memory/IO budget;
• unsupported, skinned, deforming, translucent, and custom-vertex content stays on a documented compatibility path.

Offline format

The cooker must emit a versioned, endian-defined format containing:

• cluster vertex/index payloads with bounded size (choose and document limits after GPU/cache experiments);
• object-space AABB/sphere, normal cone, geometric error, parent/child links, and material ranges;
• page grouping optimized for locality plus content hashes and dependency records;
• a coarse always-resident fallback hierarchy;
• source-to-cooked provenance for deterministic rebuilds.

Do not lock the public API to an internal cluster size.

Runtime architecture

1. Register virtual meshes and allocate stable mesh/page IDs.
2. Maintain residency/page table and request queue with per-frame upload/eviction budgets.
3. Cull instances, then traverse cluster hierarchy on GPU to projected-error targets.
4. Test selected clusters against previous-frame Hi-Z; preserve conservative behavior for newly revealed content.
5. Emit indirect commands/visibility IDs consumed by perf ticket 009: GPU-driven rendering — indirect multi-draw + GPU cull #28/perf ticket 008: visibility buffer (Nanite-style) replaces 4-MRT G-buffer #27.
6. Feed missing-page requests back asynchronously; render the nearest resident ancestor until data arrives.
7. Expose counters/debug views: selected LOD, rejected reason, page residency, requests, fallback clusters, triangles submitted/rasterized.

Quality behavior

• LOD error is expressed in pixels and scaled by quality tier/render resolution.
• Transitions must not crack. Prefer seamless hierarchy topology; use temporal/dither transitions only where necessary and test ghosting.
• Camera cuts and fast motion may reduce occlusion efficiency but may not make geometry disappear.
• Material boundaries and UV/tangent continuity must survive cluster construction.

Acceptance criteria

• Import and render a static stress asset with at least 10 million source triangles under a configurable residency budget.
• Camera motion produces no holes, cracks, missing-page flashes, or unbounded temporal trails in the fixed motion corpus.
• Projected geometric error remains at or below the selected pixel threshold in an automated image/geometry test.
• GPU culling and submission time scale primarily with candidate/visible clusters, not source triangle count; attach uncapped timings and counters.
• Peak geometry residency respects its configured budget within one page plus explicitly measured staging overhead.
• Skinned/translucent/deforming content is routed to the compatibility path with correct depth/composition and an inspectable reason.
• Asset corruption/version mismatch fails with a useful message and never reads arbitrary offsets.
• Existing immediate-mode and ordinary glTF models still render unchanged.

Likely files

• tools/bloom-cook/
• new cooked geometry modules under native/shared/src/
• native/shared/src/renderer/scene_pass.rs, hiz.rs, graph.rs, shaders
• native/shared/src/models*.rs and scene data ownership
• src/models/ and world asset metadata as needed

Verification

Attach cooker determinism hashes, residency/culling statistics, fixed-camera stills, motion-sequence diffs, and before/after GPU captures on at least one discrete and one integrated GPU.

Non-goals

• Skinned-mesh virtualization.
• Runtime arbitrary topology editing.
• Making mesh shaders mandatory; use them only as an optional backend after feature/correctness qualification.

[proggeramlug]

Issue #131 cooked-geometry v1 evidence

This checkpoint establishes Bloom's opt-in offline meshlet/page artifact at
revision 59c8df7. It does not enable a virtualized runtime path or change
accepted pixels.

Static geometry proof

Two independent release cooks of
examples/renderer-test/assets/DamagedHelmet.glb are byte-identical:

• source: 15,452 eligible triangles;
• output: 258 leaf meshlets in 20 pages;
• page budget: 65,536 bytes;
• largest page: 63,216 bytes;
• payload: 1,230,128 bytes;
• complete artifact: 1,264,592 bytes;
• artifact SHA-256:
  df089b23324fe8a8e00842a80b44894fd27b276c9124b8ff81dd77f8cf7b2cd2;
• payload SHA-256:
  67b0352a54d3d669d76d688f94899bcb8a665c561587123ea85d5d6a2b1061b0.

The default 64-vertex/124-triangle leaf limits and 64 KiB page budget
therefore hold for a canonical textured glTF asset. Material identity and all
static shading vertex attributes remain in the artifact.

Compatibility proof

examples/test-gltf-watch/assets/Fox.glb produces a valid 176-byte
metadata-only artifact:

• zero meshlets/pages/payload bytes;
• mesh 0, primitive 0 records the stable skinned reason;
• artifact SHA-256:
  5e4125b6ba31649f5ebbd694d79242e19fdb0c561073beee08f490c12be063e2.

The cooker does not reinterpret skinned geometry as static or silently omit
the reason. Equivalent records exist for morph targets, BLEND materials, and
non-triangle topology.

Integrity and determinism gates

Thirteen release tests plus strict Clippy pass. They cover:

• deterministic triangle-order partitioning and byte-exact serialization;
• hard vertex/triangle/page limits and independently hashed pages;
• conservative AABB/sphere/normal-cone construction;
• deterministic missing-normal generation;
• real GLB buffer import without image decoding;
• metadata-only compatibility artifacts;
• atomic replacement of an existing artifact;
• rejection of bad magic/version/endian, non-canonical or overlapping ranges,
  truncated data, payload corruption, invalid indices, invalid hierarchy
  links, bad counts/stride/bounds, and NaN/Inf data.

The repository's quick quality-contract component runs format, Clippy, and
release tests for bloom-cook; it passed in one second from a warm build.
geometry-inspect validates the full file before reporting any records.

Runtime neutrality

This commit changes only tools/bloom-cook, documentation, and its CI gate:

• zero production render passes or draws;
• zero runtime buffers, images, allocations, bindings, or shader branches;
• zero changes to ordinary glTF/immediate-mode dispatch;
• zero engine/runtime dependencies.

The current artifact contains leaf clusters only. Runtime loading, hierarchical
LOD construction, coarse fallback clusters, residency, GPU traversal, and
streaming remain later #131 milestones and must be qualified before any
end-state acceptance box is checked.

The detailed format and compatibility contract is in
docs/virtualized-geometry.md.

[proggeramlug]

Atomic hierarchy cooker checkpoint is now pushed in 845ff9c with qualification evidence in f8308d1 (PR #147).

What this adds:

• atomic child/parent cluster-group relations in the existing 128-byte v1 record;
• locality-aware 64v/124t leaves and multi-level attribute-aware simplification;
• locked group borders, complete shading attributes, conservative group bounds, and accumulated absolute error;
• strict reciprocal/range/level/error/root validation plus a corruption negative test;
• explicit compatibility routing remains unchanged.

Damaged Helmet (--hierarchy-levels 8): 15,452 leaf triangles / 247 leaf clusters -> 4,510 triangles / 100 level-3 coarse roots (70.8% triangle and 60.2% raw-payload reductions). Two independent artifacts are byte-identical: 57f8cc200da84c7ab63cdcd7bf02cb0c8336a96777a2ccb7fc49beaa0af3fd10.

Regression controls:

• the default leaf cook remains byte-identical to the prior qualified artifact (df089b23...);
• Fox remains the exact 176-byte skinned compatibility artifact (5e4125b6...);
• 16 release tests, fmt, strict Clippy, and strict archive inspection pass;
• shipping runtime delta remains zero passes/draws/buffers/branches/pixels.

I checked only the corruption/version-mismatch acceptance box. The unchanged-rendering box stays open until runtime integration is exercised end-to-end; stress asset, projected-pixel error, residency, GPU scaling, motion, and compatibility composition also remain open.

Evidence: docs/evidence/issue-131-atomic-hierarchy-v1.md and machine-readable JSON.

[proggeramlug]

Coarse-page placement checkpoint is pushed in fe92915, with evidence in c22d89e.

The qualified hierarchy is now remapped coarse-first without breaking atomic parent/child ranges. Root/streamable classes and LOD levels cannot share a page, roots must be the page-table prefix, and the strict reader rejects violations.

Damaged Helmet: all 100 roots occupy the first 8 pages; 468,570 raw root bytes become 469,360 logical page bytes (790 bytes packing overhead; 524,288-byte upper bound if a runtime allocates fixed 64 KiB slots). Total geometry payload is unchanged; page separation adds one 64-byte page record. Two outputs are byte-identical (da0f68d7...), the default leaf artifact remains byte-identical, and 17 release tests plus strict Clippy pass.

No runtime acceptance box is checked: this makes the coarse upload boundary exact, but runtime allocation/staging, eviction, ancestor fallback, stress residency, and GPU traversal still require their own evidence.

Evidence: issue-131-coarse-page-prefix-v1.md and JSON.