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

M03-RND-FACADE-001 — Renderer facade first seam

Ownership

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

Outcome

Introduce WorldRenderFacade as the only runtime/tool caller surface for typed streaming focus updates and read-only renderer metrics, while retaining StreamingWorldLoader as the unchanged internal implementation.

Non-goals

• Extract the pure target planner or budget scheduler in this package.
• Add environment or entity-presentation commands before their contracts exist.
• Replace the M02 TerrainQuery gameplay boundary in this package.
• Change streaming radii, queues, cache formats, visuals or quality presets.
• Mark M03 complete or edit its checklist/Evidence.

Paths

• Exclusive: src/render/world_render_facade.gd, src/tools/verify_world_render_facade.gd, this claim
• Shared/hotspots: both runtime streaming scenes, three renderer capture/probe tools, src/tools/verify_streaming_focus.gd, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md
• Generated/ignored: local .godot, native build outputs, caches and proprietary renderer corpus

Contracts and data

• Public API: set_streaming_focus, refresh_streaming_focus, renderer_metrics_snapshot
• Scene adapter: explicit streaming_focus_source_path owned by the facade
• Internal implementation seam: streaming_world_loader_path; callers must not read streamer queues or call its methods directly
• Schema/cache/coordinate contracts: unchanged
• Consumers: runtime scenes, capture tool and renderer probes

Dependencies

• Requires: M01 StreamingFocus and merged M02 closeout on master 4f566b1
• Blocks: environment/entity/ground facade contracts and planner extraction
• External state: none; contract verification uses a test double

Verification

• Commands: dedicated facade verifier, streaming-focus regression, renderer baseline manifest/dry-run, coordinate boundary and repository gates
• Fixtures: typed focus, source Node3D and read-only metrics test double
• Fidelity evidence: no renderer configuration, planner, queue, placement, visibility, material, animation or cache behavior changes
• Performance budget: one source position sample per process frame; target recomputation remains throttled inside the existing streamer

Documentation deliverables

• Inline public API docs for facade properties and methods
• Updated world-renderer module specification
• Updated data-flow, sequence and dependency diagrams
• Updated source map/status and renderer notes

Simplicity and naming

• Important names: WorldRenderFacade, renderer_metrics_snapshot
• Simplest approach: one small Node adapter delegating to the existing streamer
• Rejected complexity: service container, generic command bus, streamer rewrite or duplicate queue/cache state
• Unavoidable complexity: scene-relative source and implementation paths are resolved on the main thread with explicit diagnostics
• Measured optimization evidence: not applicable; behavior-preserving seam

Status

• State: ready-for-review
• Done: introduced the facade, migrated two runtime scenes and three renderer tools, added regression coverage and updated renderer documentation
• Next: M03 integrator reviews and merges 3d528e3
• Blocked by:

Handoff

• Commit: 3d528e3
• Integration: accepted in master merge a100ced
• Results: WorldRenderFacade is the runtime/tool surface for typed focus and detached metrics; the existing streamer remains the sole owner of queues, caches, tasks, nodes and RIDs.
• Verification: facade delegation=3 runtime_scenes=2 tools=3; streaming focus contract=1 runtime_scenes=2 capture_tools=3; coordinate boundary files=105 native_boundary=1 oracle=1 consumers=5 classifier_cases=6; render manifest checkpoints=7 coverage=7 caches=7; seven-checkpoint headless dry-run; coordination/documentation/diff gates passed.
• Fidelity: no changes to renderer target calculation, budgets, queue order, cache versions, placement, visibility, materials or animation. The dry-run retained all seven checkpoint plans. No build-12340 parity claim is added.
• External/local inputs: ignored native DLL and generated ADT resource scripts were copied from master only to run the worktree smoke. Proprietary extracted ADT and character GLB data were unavailable, producing the expected dry-run degraded-data diagnostics.
• Remaining risks: environment, entity visuals and ground query are not yet facade contracts; streamer exported configuration remains transitional scene composition; focus-source sampling adds one small main-thread adapter step per process frame while target refresh remains streamer-throttled.
• Documentation updated: inline facade API, docs/modules/world-renderer.md public API/inputs/outputs/data-flow/sequence/ownership/recovery/status/source map, and RENDER.md file map plus implementation note.