# M03 — Renderer Facade and Safe Extraction

<!-- OPENWC_TARGET:ACTIVE -->

## Outcome

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

## Steps

- [x] Ввести `WorldRenderFacade` для focus, environment, entity visuals, ground query и metrics.
- [x] Запретить gameplay/editor доступ к внутренним очередям streamer.
- [x] Извлечь pure `StreamingTargetPlanner`.
- [x] Извлечь `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`, `396be5e`, `f88bf97`;
  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`,
  `M03-RND-M2-PLACEMENT-TRANSFORM-001`,
  `M03-RND-M2-PLACEMENT-GROUPER-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.
  M2 placement transform resolver passed `cases=9 iterations=10000
  elapsed_ms=27.409`; post-merge M2 registry, internal-access `42`, facade,
  `7/7` manifest, documentation and coordination gates remained green.
  M2 placement grouper passed `cases=9 iterations=100 placements=256
  elapsed_ms=67.104`; post-merge transform resolver, registry, internal-access
  `42`, facade, `7/7` manifest, documentation and coordination gates remained green.
  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.
  M2 regular Euler, Elwynn cliff-rock shell correction, waterfall yaw/local-axis
  twist, tall-waterfall anchor compensation, path normalization and caller scale
  clamps are unchanged across worker grouping, placeholders and direct instances.
  M2 worker grouping retains invalid-record filtering, case-sensitive lowercase
  `.mdx/.mdl` conversion, first-seen group/per-group placement order, tile-local
  origin subtraction and the `0.0001` scale clamp.
  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, stateless M2 placement transform resolver and
  three transform consumers, stateless M2 placement grouper and worker adapter,
  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
  asset-backed visual transform recheck, grouping/build/tasks/caches/finalization
  and boundary traversal p95/p99 remain pending; path grouping is not yet
  culling-driven spatial-cell grouping;
  M03 still needs further terrain/M2/WMO/liquid service extraction
  and dependency/performance acceptance.
