[SOLID] [C5] Consume or delete dead segregated worldgen interfaces

[MichaelFisher1997]

Part of #776 — SOLID architecture debt umbrella.
Phase: P2 · Finding: C5

Problem

modules/worldgen-api/src/root.zig:139-177 defines IChunkGenerator, ILODHeightmapGenerator, IGeneratorInfoProvider, ICacheRecenterable — but no consumer uses them. The registry demands the full fat 7-method Generator, forcing FlatWorldGenerator and ShadowTestWorldGenerator to publish no-op shims for methods semantically meaningless to them.

Evidence

worldgen-flat/src/root.zig:68-90:

pub fn generateHeightmapOnly(...) void {
  _ = self; _ = region_x; _ = region_z; _ = lod_level; _ = stop_flag;
  @memset(data.heightmap, @floatFromInt(FLAT_HEIGHT));  // constant
}
pub fn maybeRecenterCache(...) bool {
  _ = self; _ = player_x; _ = player_z;
  return false;  // flat world has no cache
}

Fix

Two options — pick one:
A) Consume them: split registry registration into 'chunk-only' vs 'chunk+LOD'. Flat/test generators register as chunk-only and skip the LOD vtable entries.
B) Delete them: remove the 4 interfaces and accept the fat Generator as the contract.

Recommend A if a future generator might be chunk-only; B if simplicity wins.

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

Decision needed before implementation. The no-op shims are misleading either way.

Tracking: #776

[github-actions]

I have analyzed the issue and verified the findings against the codebase. Here is my analysis:

Classification

Refactor / Architectural Debt — sub-issue of #776, Phase P2 finding C5. The automated-audit label is present, so this is a trusted machine-generated finding.

Validation of findings

I verified the claim by grepping the entire codebase for the four interface names. They appear in exactly four files:

• modules/worldgen-api/src/root.zig:139-177 (definitions)
• modules/worldgen-overworld/src/generator_interface.zig:10-13 (passthrough re-export)
• modules/world-worldgen/src/generator_interface.zig:10-13 (passthrough re-export)
• modules/world-worldgen/src/root.zig:77-80 (passthrough re-export)

No file consumes them as types or values — the four interfaces are pure dead code wrapped behind three layers of trivial re-export shims. The fat Generator (vtable of 7 methods at worldgen-api/src/root.zig:82-90) is what the registry and runtime actually call.

The cited no-op shim locations are accurate in spirit (worldgen-flat/src/root.zig:68-93 for generateHeightmapOnly, line 95 for maybeRecenterCache; worldgen-test/src/root.zig:166-197 has the same pair).

Scope assessment

This is appropriately scoped — a single, contained refactor in one API module plus removal of redundant re-exports. Not too broad for a single PR.

Architectural analysis

Option A (consume) — would require:

• Teaching GeneratorDescriptor / registry.zig to declare which facets a generator implements (chunk-only, chunk+LOD, recenterable).
• Adding runtime guards at every call site that invokes generateHeightmapOnly / maybeRecenterCache (currently invoked unconditionally via the fat vtable).
• Updating FlatWorldGenerator / ShadowTestWorldGenerator to omit no-op methods and document that they don't implement those facets.

Option B (delete) — is a one-shot deletion of 39 lines plus the three re-export lines. Zero behavior change, zero call-site migration, zero new state machine.

Trade-off — Option A only pays off if a chunk-only generator is genuinely on the roadmap. Today none exists, and the no-op shims are short, explicit, and clearly labelled (_ = self; ... return false). The audit scorecard (P5) explicitly calls worldgen LSP "strong" — the shims are not silently lying about behavior.

Recommendation

Go with Option B. Reasons:

1. YAGNI — no concrete chunk-only generator exists to justify the segregation.
2. Lower risk — pure deletion, no call-site migration, no new invariant to maintain in registry.zig.
3. Honest contract — Option A would still require Generator (or a registry-level union) to dispatch across facets, re-introducing complexity to solve a problem that the fat vtable already handles with three-line shims.
4. Future flexibility — if a chunk-only generator ever arrives, the segregated interfaces can be reintroduced with a real consumer, which is easier to design than today.

Option A becomes attractive only if the team is also willing to take on the related M9 work (registry.zig:51-65 factory duplication) in the same PR — otherwise the interface split lives in an awkward halfway state.

Verification baseline

For a behavior-preserving deletion:

• nix develop --command zig build test (must stay green; shader validation included)
• No headless screenshot needed — purely an API surface change with no rendering impact.

Minor housekeeping this PR can absorb

If Option B is chosen, the PR should also drop ICacheRecenterable/IChunkGenerator/IGeneratorInfoProvider/ILODHeightmapGenerator from the three re-export shims to avoid leaving dangling references. This naturally aligns with M18 from the umbrella audit (collapse the triplicated generator_interface shim — same files).

Scope

Single small PR targeting dev, conventional commit refactor: remove dead segregated worldgen interfaces (C5). No breaking API change for downstream generator implementations since the four interfaces are already unused.

opencode session  |  github run