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

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

<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-GROUND-QUERY-001:9408d88 -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-FACADE-GROUND-QUERY-001:d6e5b53 -->

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