diff --git a/coordination/claims/M03-RND-FACADE-GROUND-QUERY-001.md b/coordination/claims/M03-RND-FACADE-GROUND-QUERY-001.md new file mode 100644 index 0000000..26d3607 --- /dev/null +++ b/coordination/claims/M03-RND-FACADE-GROUND-QUERY-001.md @@ -0,0 +1,81 @@ +# 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: