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

<!-- OPENWC_CLAIM:M03-RND-FACADE-GROUND-QUERY-001:sindo-main-codex:2026-07-18 -->

## 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: