open-wc/targets/03-renderer-facade.md

M03 — Renderer Facade and Safe Extraction

Outcome

Закрыть монолитный streamer стабильным API и постепенно извлечь тестируемые подсистемы без rewrite.

Steps

• Ввести WorldRenderFacade для focus, environment, entity visuals, ground query и metrics.
• Запретить gameplay/editor доступ к внутренним очередям streamer.
• Извлечь pure StreamingTargetPlanner.
• Извлечь RenderBudgetScheduler с bounded queues/cancellation.
• Затем извлекать terrain, M2, WMO и liquid services по одному.
• Сохранить cache versioning и main-thread GPU finalization rules.
• Добавить dependency и performance regression checks.

Fidelity evidence

Все baseline checkpoints сравниваются до/после; placement, visibility, animation и materials не меняются без отдельной fidelity-задачи.

Exit criteria

Runtime и Editor используют facade; planner/scheduler тестируются без полного мира; p95/p99 и hitch budgets не хуже согласованного baseline.

Evidence

• Date: 2026-07-16
• Revision/worktree: master merges 7ece2ab, 7e35de7, 80cb084, d6e5b53, c69abd6, 606770c, 630a0c1, f36fabb, 24aef13, 2342430; packages M03-RND-SCHEDULER-001, M03-RND-INTERNAL-ACCESS-GATE-001, M03-RND-FACADE-GROUND-QUERY-001, M03-RND-FACADE-ENVIRONMENT-001, M03-RND-FACADE-ENTITY-001, M03-RND-TERRAIN-CACHE-SERVICE-001, M03-RND-TERRAIN-LOD-PLANNER-001, M03-RND-TERRAIN-CHUNK-QUEUE-001, M03-RND-M2-UNIQUE-REGISTRY-001
• Commands: dedicated scheduler/planner/facade/focus/coordinate/manifest/shutdown headless verifiers; Godot cold editor parse; coordination, documentation and diff gates.
• Results: scheduler cases=6 iterations=20000 elapsed_ms=10.216; planner cases=5 average_ms=1.804; facade/focus passed; coordinate boundary files=111 consumers=6; renderer manifest retained 7/7 checkpoints; shutdown ownership and repository gates passed. Internal-access gate additionally derived 43 private symbols and found no forbidden access across 7 gameplay and 9 EditorPlugin-package sources plus the terrain probe. Ground facade passed delegation=5 ground_contract=2; cold RenderedGroundSample contract=3; environment integration passed cold snapshot contract=5 and facade delegation=6 environment_contract=7; dry-run retained all 7/7 plans and applied the dusk checkpoint at time=19.00. Entity presentation passed snapshot_cases=8 lifecycle_cases=14 runtime_scenes=2; facade expanded to delegation=9 entity_contract=6, while character presentation remained 9/10/3/1. Terrain quality cache passed contract_cases=15 loader_calls=3; internal-access inventory decreased to 42 because the loader no longer owns the LRU-order field. Terrain chunk LOD planner passed cases=7 iterations=250 elapsed_ms=12.630; post-merge facade, internal-access and 7/7 manifest gates remained green. Terrain chunk geometry queue planner passed cases=8 iterations=100 elapsed_ms=229.324; internal-access remained 42 and post-merge facade and 7/7 manifest gates stayed green. M2 unique placement registry passed cases=10 iterations=100 elapsed_ms=35.513; the historical uid:11785 cross-tile smoke, internal-access 42, facade and 7/7 manifest gates remained green after merge. M02 terrain-query regression remained green (13 pre-existing expired M00 claim warnings).
• Fidelity comparison: all 16 historical operation limits and drain sites were preserved; chunk removal/create retain their shared removal-first budget. Defaults, quality presets, cache versions and visual rules are unchanged. Rendered-ground diagnostics preserve the prior 5000-unit ray, 3x3 search and 2/5/10/20/40-unit nearby fallback while hiding mutable renderer state. Environment snapshots preserve the prior fixed-clock assignments while DBC profile/area/skybox selection, interpolation, fog, sun and shader rules remain unchanged. Runtime produces no world-entity commands yet, so player/world output and all baseline plans remain unchanged by the new present/remove ownership boundary. Terrain revisit cache retains the same admitted/excluded sources, LRU touch/trim, profile capacities and three loader adapter sites; no cache format changed. Chunk LOD keeps horizontal XZ chunk-center distance, inclusive squared thresholds, sparse-index omission and raw negative-radius squaring at both loader call sites. Chunk operation planning preserves stable removals, nearest-first create sorting, tile-LOD remove-all takeover, sparse tile-origin fallback and XZ-only distance; loader still drains removals first through the shared chunk_geometry budget. M2 positive MDDF.uniqueId retains uid:<decimal> first-owner semantics, within-call duplicate suppression, cross-tile skip/retry and unkeyed pass-through. No new build-12340 parity claim is made; asset-backed visual/p95/p99 comparison remains pending.
• Changed files: scene-free scheduler and verifier; streamer budget composition/ permit delegation; scheduler module spec; world renderer/module registry/RENDER notes; renderer-owned ground sample, facade/loader ground query, migrated terrain probe, immutable environment snapshot, facade/sky adapter, migrated checkpoint time input, contract-v1 entity snapshot, renderer-owned entity presenter, runtime composition, scene-free terrain quality Mesh cache and loader store/restore/clear adapters, immutable terrain chunk LOD policy, pure planner and both loader plan adapters, pure terrain chunk geometry queue planner and loader queue-adoption adapter, stateful M2 unique placement registry, loader reserve/release/clear adapters and migrated historical dedupe smoke, expanded facade/internal-access/coordinate verifiers; work-package claims and this evidence.
• Remaining risks: queue storage length and worker concurrency/stale-result logic remain streamer-owned; cancellation stops new permits but does not interrupt in-flight work; the environment snapshot currently covers world time but not weather or indoor state; entity PackedScene loading is synchronous and not accepted for network-scale hot paths; terrain cache is entry-count bounded without Mesh-byte metrics and the remaining terrain build/tasks/state/finalization stay monolithic; chunk LOD asset-backed p95/p99 and visual acceptance remain pending; chunk queue planning adds a second tile-state pass whose asset-backed p95/p99 still needs acceptance, while queue drains and geometry finalization remain monolithic; private Azeroth data was absent for the asset-backed ADT placement probe; M2 grouping/build/tasks/caches/finalization and boundary traversal p95/p99 remain pending; M03 still needs further terrain/M2/WMO/liquid service extraction and dependency/performance acceptance.