open-wc/coordination/claims/M03-RND-FACADE-GROUND-QUERY-001.md

M03-RND-FACADE-GROUND-QUERY-001 — Rendered ground query facade

Ownership

• Target: M03
• Program: RND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m03-facade-ground-query
• Lease expires UTC: 2026-07-18
• Integrator: M03 milestone integrator

Outcome

Expose typed ground-height sampling and a detached readiness diagnostic through WorldRenderFacade, using already loaded render terrain meshes, and migrate the terrain-height probe away from direct streamer state/queue access.

Non-goals

• Replace the M02 gameplay-owned TerrainQuery/AdtTerrainQuery composition.
• Make rendered mesh sampling authoritative for movement, collision or server state.
• Add slopes, holes, liquid, WMO/M2 collision or async query callbacks.
• Change terrain meshes, streaming policy, queue order, cache formats or visuals.
• Complete environment/entity-visual facade contracts or mark M03 complete.

Paths

• Exclusive: this claim
• Shared/hotspots: src/render/world_render_facade.gd, src/scenes/streaming/streaming_world_loader.gd, src/tools/probe_render_terrain_height.gd, src/tools/verify_world_render_facade.gd, src/tools/verify_renderer_internal_access.gd, docs/modules/world-renderer.md, docs/modules/terrain-query.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated ADT resource scripts, extracted renderer corpus and probe reports

Contracts and data

• Input: immutable GodotWorldPosition in Godot world units
• Output: renderer-owned immutable RenderedGroundSample plus optional detached diagnostic Dictionary
• Sampling source: loaded quality or tile-LOD Mesh and its live tile transform
• M02 ADT query cache, renderer cache versions and coordinate contracts: unchanged

Dependencies

• Requires: M02 terrain query contract and integrated M03 facade/access gate 53d84cc
• Blocks: removal of renderer diagnostic internal-access exception and later terrain service extraction
• External state: asset-backed probe is optional; contract tests use a facade double

Verification

• Commands: facade query/snapshot isolation contract, internal-access gate, terrain-query regression, focus/coordinate/manifest/shutdown regressions and repository gates
• Fixtures: available/unavailable sample, detached diagnostic, probe source migration
• Fidelity evidence: mesh ray/nearest fallback algorithm moves unchanged from the probe
• Performance budget: on-demand diagnostic query only; no per-frame query added

Documentation deliverables

• Inline facade/streamer API docs
• World-renderer API/data-flow/sequence/ownership/recovery/source-map updates
• Terrain-query backend status/ownership clarification and renderer implementation note

Simplicity and naming

• Important names: sample_ground_height, renderer_ground_query_snapshot
• Simplest approach: one typed facade query over one existing diagnostic read model
• Rejected complexity: duplicate ADT cache, physics service, callback bus, query node, generic spatial interface or new dependency
• Unavoidable complexity: triangle-mesh ray query retains the existing bounded nearby fallback for seam/edge diagnostic behavior

Status

• State: ready-for-review
• Done: added renderer-owned typed sample, facade query/snapshot, migrated terrain probe, expanded internal-access/coordinate gates and updated module docs
• Next: M03 integrator reviews and merges b697a89 plus cold-start fix 9408d88
• Blocked by:

Handoff

• Commits: implementation b697a89; cold-start fix 9408d88
• Results: WorldRenderFacade delegates loaded-mesh ground sampling and returns renderer-owned RenderedGroundSample; detached diagnostic snapshots preserve the probe report while hiding queue/tile/Mesh/Node references. Gameplay remains on the independent M02 TerrainQuery composition.
• Verification: facade delegation=5 ground_contract=2 runtime_scenes=2 tools=3; cold rendered-ground value contract=3 from an empty Godot class cache; internal access private_symbols=43 gameplay=7 editor_sources=9 renderer_tools=1; terrain query contracts passed; coordinate boundary files=113 consumers=5; renderer manifest 7/7; shutdown ownership, scheduler/planner, coordination, documentation and diff gates passed.
• Fidelity: the probe's 5000-unit ray height, 3x3 tile search, highest-hit choice, readiness fields and 2/5/10/20/40 nearby fallback moved unchanged. No terrain geometry, streaming, cache, material, placement or visual rule changed. No build-12340 parity claim is added.
• External/local inputs: ignored native DLL and generated ADT resource scripts were copied from master only for editor/streamer parse and then removed. Proprietary extracted world data was unavailable, producing expected degraded diagnostics.
• Remaining risks: triangle-mesh generation is on-demand/main-thread and diagnostic; it is unsuitable for per-physics-frame gameplay; exact asset-backed probe output still depends on local corpus readiness; environment/entity facade contracts remain.
• Documentation: inline facade/loader/value API; world-renderer API/data-flow/ sequence/ownership/recovery/capability/source map; terrain-query authority clarification and renderer implementation notes updated.
• Integration: implementation accepted in master merge 80cb084; cold-start fix accepted in merge d6e5b53. Post-merge cold/facade/access/terrain/coordinate/ manifest/shutdown/scheduler/planner/focus and repository gates passed.