[SOLID] [M5] Extract LightingEngine from world_mutation.zig

[MichaelFisher1997]

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

Problem

modules/world-runtime/src/world_mutation.zig:53-92, 137-422 is marketed as 'the single path for block edits' but embeds a complete BFS lighting propagation engine (~285 lines): spreadSkylight, spreadBlockLight, seedSunlightColumn, seedLightFromNeighbors, recomputeLoadedLightingArea, relightAfterBlockRemoval.

Evidence

world_mutation.zig:53-92 — one coordinator doing block-write + GPU signal + flood-fill lighting:

pub fn applyBlockMutation(...) !?MutationResult {
  ...
  data.chunk.setBlock(local.x, local.y, local.z, block);
  if (self.gpu_mesher_active) { ... buf.updateBlock(...); }
  ...
  if (block == .air and old_def.isOpaque() ...) {
    try self.relightAfterBlockRemoval(...);     // BFS engine
  } else if (...) {
    try self.recomputeLoadedLightingArea(...);  // BFS engine
  }
}

Fix

Extract the BFS engine into a LightingEngine module (e.g. modules/world-runtime/src/lighting_engine.zig or world-lighting). The coordinator invokes lightingEngine.afterBlockRemoval(...) / .recomputeArea(...).

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

Behavior-preserving. The lighting algorithm is unchanged — only its home moves.

Tracking: #776

[github-actions]

Audit Validation — Issue #788 (M5 of #776)

Classification: Refactor (SOLID — Single Responsibility Principle). Not a bug; the lighting algorithm is correct. This is technical-debt cleanup.

Evidence verified against modules/world-runtime/src/world_mutation.zig:

• L53-92 applyBlockMutation — mixed-concern coordinator (block write + GPU signal + BFS relight). ✓
• L137 recomputeLoadedLightingArea ✓
• L166 relightAfterBlockRemoval ✓
• L255 seedSunlightColumn ✓
• L278 seedLightFromNeighbors ✓
• L311 spreadSkylight ✓
• L343 spreadBlockLight ✓
• File total = 556 lines; L137-422 spans the BFS engine as claimed (~285 lines).

Duplicate / related-work scan:

• No existing PR targeting dev for a LightingEngine extraction.
• No duplicate issue. #776 (umbrella) is still OPEN and tracks this as a sub-finding.

---

Recommended implementation outline (behavior-preserving)

1. New module: modules/world-runtime/src/lighting_engine.zig — sibling, not a new top-level package (matches existing layout; lighting is a runtime concern driven by mutations). If the team later wants stronger isolation, a world-lighting package is reasonable but YAGNI for now.
2. API surface (pure functions or thin struct holding *ChunkStorage + Allocator):
   • LightingEngine.afterBlockRemoval(cx, cz, lx, ly, lz)
   • LightingEngine.recomputeArea(cx, cz, lx, lz)
   • Internal: seedSunlightColumn, seedLightFromNeighbors, spreadSkylight, spreadBlockLight — move verbatim.
   • Keep LightPos / RgbLightPos types inside the new module.
3. WorldMutationCoordinator shrinks to:
   • data.chunk.setBlock(...)
   • GPU buffer updateBlock(...)
   • try lighting.afterBlockRemoval(...) or lighting.recomputeArea(...)
   • invalidateNeighbors(...)
     The else if (old_emission != new_emission) branch decides which engine call is made.
4. Threading constraint preserved: BFS already runs on the calling thread (mutation is main-thread); no RHI calls added or moved. Verify there are no defer-ed GPU calls inside the extracted functions — applyBlockMutation's GPU write stays in the coordinator.
5. Tests: behavior-preserving ⇒ golden-output/world-load tests must stay green. Add focused unit tests on LightingEngine for:
   • Air removal of an opaque block floods skylight to the column.
   • Block-light emitter placed → propagates until neighbour is opaque.
   • Boundary edit (lx==0/lx==15/lz==0/lz==15) crosses into neighbour chunks via seedLightFromNeighbors.

Suggested PR scope

Single PR, ~285 lines moved + ~20 lines of new wiring + tests. Not a multi-PR split — the functions share LightPos/RgbLightPos and queue-management invariants, so partial extraction would create cross-file coupling rather than fix it. Break it up only if world_mutation.zig becomes a world-runtime re-export in a later M-finding (e.g. M6/M7 from #776).

Suggested commit

refactor(world-runtime): extract LightingEngine from WorldMutationCoordinator

Move BFS relight functions (spreadSkylight, spreadBlockLight,
seedSunlightColumn, seedLightFromNeighbors, recomputeLoadedLightingArea,
relightAfterBlockRemoval) into a dedicated LightingEngine module so the
mutation coordinator only writes blocks and signals the GPU.

No behavior change. #776 (M5)

Action requested

• Confirm target location: modules/world-runtime/src/lighting_engine.zig vs a new world-lighting package. I'd default to the former to avoid cross-module queue-type leakage.
• Confirm automated-audit issues in this repo are tracked via the umbrella #776 (no separate milestone needed for M5).

[github-actions]

Comment posted on #788: #788 (comment)

Summary of the analysis:

• Type: Refactor (SOLID/SRP), not a bug — algorithm unchanged, only the home moves.
• Evidence verified: All 6 lighting functions found at the cited line numbers; coordinator at L53-92 matches.
• No duplicates: No open PR or duplicate issue; tracked under umbrella [Audit][Umbrella] SOLID architecture debt: RHI seam leakage, god-objects, and extension-safety gaps #776.
• Scope recommendation: Single PR (~285 LOC move + wiring + tests). Splitting would create cross-file coupling on LightPos/RgbLightPos instead of fixing the god-object.
• Target location: Default to modules/world-runtime/src/lighting_engine.zig; new world-lighting package is YAGNI until a later M-finding demands it.
• Constraint: Mutation path stays main-thread; no RHI calls added/moved by the extraction.

opencode session  |  github run