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

<!-- OPENWC_CLAIM:M03-RND-FACADE-001:sindo-main-codex:2026-07-17 -->

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

<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-001:3d528e3 -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-FACADE-001:a100ced -->

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