[SOLID] [M6] Extract LpvGridBuilder from world.zig facade

[MichaelFisher1997]

Part of #776 — SOLID architecture debt umbrella.
Phase: P1 · Finding: M6

Problem

modules/world-runtime/src/world.zig:717-831 embeds ~115 lines of dense triple-nested voxel iteration (lpvCollectLights, lpvBuildOcclusionGrid) directly in the World facade. A lighting subsystem does not belong in the facade.

Evidence

(Full evidence and file:line citations are in the umbrella #776.)

Fix

Extract into an LpvGridBuilder collaborator (e.g. modules/engine-lighting/src/lpv_grid_builder.zig or a new world-runtime module). World holds/invokes it.

Verification

• nix develop --command zig build test (includes shader validation)
• If rendering-touching: capture headless screenshot baseline before/after (-Dskip-present)
• If behavior-preserving refactor: golden-output test must stay green

Constraints

• Small reviewable PR targeting dev; conventional commit (refactor: / feat:)
• Preserve current behavior unless this issue explicitly changes it
• Keep worker-thread RHI isolation intact (no RHI calls off main thread)

Notes

World is otherwise a clean facade (delegates to WorldStreamer/Renderer/Mutation/LOD/Save). This is the main SRP leak.

Tracking: #776

[github-actions]

Validation: M6 is real and well-scoped

I verified the cited location and surrounding plumbing. The refactor target is clear and contained.

Code pointers (confirmed)

• modules/world-runtime/src/world.zig:733-736 — LPV_VTABLE definition
• modules/world-runtime/src/world.zig:738-799 — lpvCollectLights (62 lines, triple-nested voxel loop)
• modules/world-runtime/src/world.zig:801-849 — lpvBuildOcclusionGrid (49 lines, triple-nested voxel loop)
• modules/world-runtime/src/world.zig:577-579 — lpvWorld() accessor exposing the vtable
• modules/engine-graphics/src/lpv_system.zig:22-38 — ILPVWorld interface (already in place)
• modules/engine-graphics/src/lpv_system.zig:325, 331 — sole consumer (LPVSystem.collectLights, LPVSystem.buildOcclusionGrid)

Architectural observations

1. ILPVWorld is already the abstraction seam. The vtable exists; the refactor only needs to relocate the bodies behind it. No interface redesign required.
2. engine-lighting is a re-export shim. modules/engine-lighting/src/root.zig only forwards types from modules/engine-graphics/src/lighting_root.zig (see build.zig:132, 200-205). It has no impl directory and pulling ChunkStorage/block_registry/CHUNK_SIZE_* into it would expand that module's surface significantly.
3. Cleaner extraction target: keep LpvGridBuilder inside world-runtime as a sibling of world_renderer.zig / world_mutation.zig (e.g. modules/world-runtime/src/lpv_grid_builder.zig). It naturally depends on ChunkStorage, block_registry, GpuLight, and Vec3 — all already imported in world-runtime.
4. Threading: the two functions take storage.chunks_mutex.lockShared() directly, so they're main-thread-safe and called from LPVSystem::update (render thread). No worker-thread isolation concerns — preserve the shared-lock discipline in the builder.
5. Behavior preservation: block_registry.getBlockDefinition(block) is called once per non-air block in both loops. Keep this as-is (golden output must not change). Could be a follow-up perf issue, not for this PR.

Suggested PR shape

1. New modules/world-runtime/src/lpv_grid_builder.zig exposing:

   pub const LpvGridBuilder = struct {
       storage: *ChunkStorage, // or an IChunkProvider iface for testability
       pub fn collectLights(...) usize { ... }
       pub fn buildOcclusionGrid(...) void { ... }
   };

2. World holds an lpv_grid_builder: LpvGridBuilder and the existing LPV_VTABLE becomes a 3-line shim that forwards to it.
3. lpvWorld() accessor unchanged externally — ILPVWorld consumers (only LPVSystem) see no diff.
4. Add unit tests for LpvGridBuilder against a small in-memory ChunkStorage (this is a free win the facade currently blocks).
5. Conventional commit: refactor(world-runtime): extract LpvGridBuilder from World facade targeting dev.

Scope assessment

Right-sized for a single small PR — single subsystem, behavior-preserving, no new public surface, no shader/RHI changes. No need to split.

Verification

No headless screenshot needed — this does not touch rendering. Just nix develop --command zig build test (covers shader validation + new builder unit tests).

[github-actions]

Posted validation comment on issue #789. Summary of what I confirmed:

• Real finding: world.zig:733-849 matches the cited SRP leak exactly — LPV_VTABLE + 115 lines of nested voxel iteration embedded in the World facade.
• Architecture already set up: ILPVWorld vtable exists at engine-graphics/lpv_system.zig:22 — this is just a relocation, not an interface redesign.
• Better extraction target than suggested: engine-lighting is currently a thin re-export shim with no impl directory. The cleanest home is modules/world-runtime/src/lpv_grid_builder.zig (sibling of world_renderer.zig), since it already has ChunkStorage, block_registry, and GpuLight imports.
• Scope: right-sized for a single behavior-preserving PR. No need to split. No screenshot needed — doesn't touch rendering.

opencode session  |  github run