# 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-17
- Revision/worktree: master merges `7ece2ab`, `7e35de7`, `80cb084`, `d6e5b53`, `c69abd6`, `606770c`, `630a0c1`, `f36fabb`, `24aef13`, `2342430`, `396be5e`, `f88bf97`, `3f84717`, `d2cb52f`, `f9e5a4f`, `c06aed5`, `a878e7c`, `60603e1`, `b4955d6`;
  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`,
  `M03-RND-M2-BUILD-BATCH-PLANNER-001`,
  `M03-RND-WMO-PLACEMENT-RESOLVER-001`,
  `M03-RND-WMO-PLACEMENT-REGISTRY-001`,
  `M03-RND-WMO-RENDER-BUILD-PLANNER-001`,
  `M03-RND-WMO-RENDER-BUILD-QUEUE-001`,
  `M03-RND-WMO-RENDER-RESOURCE-CACHE-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.
  M2 build batch planner passed `cases=8 iterations=20000 elapsed_ms=14.532`;
  post-merge grouper, transform resolver, registry, internal-access `42`, facade,
  `7/7` manifest, documentation and coordination gates remained green.
  WMO placement resolver passed `cases=9 iterations=20000 elapsed_ms=27.919`;
  post-merge renderer materials, shutdown, internal-access `42`, facade,
  `7/7` manifest, documentation and coordination gates remained green.
  WMO placement registry passed `cases=10 iterations=100 elapsed_ms=53.941`;
  all 21 adjacent WMO/M2/terrain/facade/scheduler/streaming/coordinate
  regressions and the `7/7` checkpoint dry-run passed; post-merge registry
  (`54.178ms`), resolver, shutdown, facade, documentation and coordination
  gates remained green.
  WMO render build step planner passed `cases=9 iterations=20000
  elapsed_ms=11.914`; WMO registry/resolver/material/shutdown, 18 adjacent
  regressions and the `7/7` checkpoint dry-run passed; post-merge planner
  (`11.059ms`), registry, resolver, shutdown, facade, documentation and
  coordination gates remained green.
  WMO render build queue passed `cases=11 iterations=100 elapsed_ms=59.874`;
  WMO planner/registry/resolver/material/shutdown, 18 adjacent regressions and
  the `7/7` checkpoint dry-run passed. The first post-merge smoke exposed an
  editor class-cache dependency; a fresh no-`.godot` run verified the fix
  (`57.835ms`), and post-fix master passed queue (`56.454ms`), planner,
  registry, resolver, shutdown, facade, documentation and coordination gates
  without parse diagnostics.
  WMO render Resource cache state passed `cases=10 iterations=100
  elapsed_ms=58.727`; direct no-`.godot` service verification passed
  (`45.361ms`), WMO queue/planner/registry/resolver/material/shutdown and 18
  adjacent regressions passed, and the checkpoint dry-run retained `7/7` plans.
  Post-merge cache state (`51.949ms`), shutdown, WMO queue/resolver, facade,
  internal-access `41`, `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.
  M2 build batching retains animated/static limit selection, minimum-one clamp,
  remaining-transform cap and the exact offset/group-completion cursor rules.
  WMO cache-key normalization, positive MODF identity with tile/index fallback
  and world position/Euler/unclamped-scale transforms are unchanged across
  lightweight render, cached-scene and live-prototype paths.
  WMO first/idempotent/shared/non-owner/final/global reference behavior is
  unchanged; the extracted registry owns only String reference sets while the
  loader retains the parallel key-to-Node map and final-release cancellation/free.
  Lightweight WMO render groups retain mesh-before-MultiMesh order, one cursor
  increment and one budget permit per valid or null group; completion still
  cancels the job after both raw integer cursor comparisons are exhausted.
  Pending WMO render builds retain typed root/resource/cursors, FIFO order,
  duplicate replacement, stale-front pop, first-occurrence cancel and three
  idempotent clear sites. Queue release never frees engine objects; the loader
  retains validity checks, materialization, permits and Node destruction.
  Lightweight WMO render cache paths retain the same cached/pending/missing
  transitions, retry behavior for absent files and map-reset versus final-shutdown
  lifetime. `ResourceLoader`, script identity and `FORMAT_VERSION` validation
  remain loader-owned before the extracted state accepts a Resource.
  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,
  stateless M2 build batch planner and loader cursor adapter,
  stateless WMO placement resolver and seven cache/identity/transform adapters,
  stateful WMO placement registry and global/tile add/release/clear adapters,
  stateless WMO render build step planner and loader cursor-adoption adapter,
  typed WMO render build job/queue and loader enqueue/drain/cancel/clear adapters,
  lightweight WMO render Resource/missing/request state and loader I/O/validation/
  reset adapters,
  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; M2 resource/queue transitions and raw
  cached-scene WMO cache/load requests, ResourceLoader I/O and group
  materialization remain in the loader;
  asset-backed WMO placement/portal/material/leak/p95/p99 evidence remains pending;
  M03 still needs further terrain/M2/WMO/liquid service extraction
  and dependency/performance acceptance.