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: immutable TerrainGroundSample 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: active
• Done: facade/backend ownership and diagnostic compatibility contract defined
• Next: move sampling behind loader/facade, migrate probe, add tests/docs
• Blocked by: