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

# M03-RND-FACADE-ENVIRONMENT-001 — Renderer environment snapshot boundary

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

## Ownership

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

## Outcome

Add an immutable world-environment snapshot accepted by `WorldRenderFacade`,
delegate it to the existing DBC sky controller, and migrate deterministic render
checkpoint time setup away from direct sky-controller property mutation.

## Non-goals

- Change Light/Area/Skybox DBC selection, interpolation, fog, sun or shader rules.
- Add weather, indoor lighting, new clock semantics or build-12340 parity claims.
- Extract the sky service or move its Environment/Node/RID ownership.
- Change runtime scene defaults, cache formats, streaming behavior or target status.

## Paths

- Exclusive: `src/render/environment/world_environment_snapshot.gd`,
  `src/tools/verify_world_environment_snapshot.gd`, this claim
- Shared/hotspots: `src/render/world_render_facade.gd`,
  `src/scenes/sky/wow_sky_controller.gd`, both runtime streaming scenes,
  `src/tools/capture_render_checkpoints.gd`,
  `src/tools/verify_world_render_facade.gd`, `docs/modules/world-renderer.md`,
  `docs/modules/README.md`, `RENDER.md`, `targets/03-renderer-facade.md`
- Generated/ignored: `.godot`, native DLL, generated resources, caches and
  proprietary renderer corpus

## Contracts and data

- Public API: immutable `WorldEnvironmentSnapshot` and
  `WorldRenderFacade.apply_environment_snapshot`
- Snapshot input: finite time-of-day hours normalized into one 24-hour day
- Adapter: explicit `world_environment_controller_path`; facade/controller retain
  no ownership of caller snapshot
- Schema/cache/coordinate contracts and runtime defaults: unchanged
- Consumer: deterministic renderer checkpoint capture; future world-state adapter

## Dependencies

- Requires: integrated M03 facade/ground-query master `cb103e1`
- Blocks: completion of the facade environment checklist slice and later sky extraction
- External state: none for contract tests; visual comparison still needs proprietary corpus

## Verification

- Commands: dedicated cold snapshot contract, facade delegation/wiring regression,
  capture source-boundary regression, renderer manifest/dry-run and repository gates
- Fixtures: normalization, non-finite rejection, missing/wrong controller,
  exact snapshot delegation and existing runtime scene wiring
- Fidelity evidence: preserve existing fixed-time application and all DBC-derived
  visual logic; seven checkpoint plans remain valid
- Performance budget: one immutable value allocation per environment update and
  constant-time main-thread delegation

## Documentation deliverables

- Inline public API docs: snapshot, facade adapter and sky-controller application
- Module specification: update existing world-renderer specification
- Data-flow diagram: snapshot producer through facade into DBC sky controller
- Sequence/state/dependency diagrams: application/failure path and ownership notes
- Source map/status updates: world-renderer module, module registry if needed, `RENDER.md`

## Simplicity and naming

- Important names introduced: `WorldEnvironmentSnapshot`, `apply_environment_snapshot`
- Simplest considered solution: one immutable time snapshot over the existing sky implementation
- Rejected complexity/abstractions: generic weather graph, duplicated lighting DTO,
  event bus, service container or alternate Environment owner
- Unavoidable complexity and justification: facade resolves a separate scene-owned
  sky controller because the streamer does not own outdoor environment rendering
- Measured optimization evidence: not applicable; bounded constant-time adapter

## Status

- State: ready-for-review
- Done: immutable value, facade/controller adapter, checkpoint migration,
  regressions and renderer module documentation
- Next: M03 integrator reviews and merges `2ee647a`
- Blocked by:

<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-ENVIRONMENT-001:2ee647a -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-FACADE-ENVIRONMENT-001:c69abd6 -->

## Handoff

- Commit: `2ee647a`
- Results: `WorldEnvironmentSnapshot` normalizes finite time into one day and
  exposes non-finite failure explicitly. `WorldRenderFacade` delegates the
  immutable value to the existing sky controller; checkpoint capture no longer
  locates or mutates that controller directly.
- Verification: snapshot `contract=5`; facade `delegation=6 ground_contract=2
  environment_contract=7 runtime_scenes=2 tools=3`; internal access `43/7/9/1`;
  terrain, coordinate (`files=116 consumers=5`), manifest (`7/7`), shutdown,
  scheduler (`20000` iterations), planner (`250` iterations), focus, editor parse,
  dry-run capture, coordination, documentation and diff gates passed.
- Fidelity: applying a snapshot retains the previous three fixed-clock assignments
  and leaves DBC profile/area/skybox lookup, interpolation, fog, sun, shader,
  cache and streaming rules unchanged. Dry-run retained all seven plans and
  reported dusk as `time=19.00`. No build-12340 parity claim is added.
- External/local inputs: ignored native DLL and generated ADT resource scripts
  were copied from master for parse/dry-run only. Missing proprietary ADT/DBC/
  character data produced expected degraded diagnostics.
- Remaining risks: the snapshot currently covers exact world time only; weather,
  indoor state and asset-backed paired zone-transition evidence remain open.
- Documentation updated: inline value/facade/controller API plus world-renderer
  API/input-output/data-flow/sequence/ownership/failure/capability/source-map and
  `RENDER.md` implementation notes.
- Integration: accepted in master merge `c69abd6`; post-merge snapshot, facade,
  internal-access, manifest, shutdown, scheduler, planner and focus gates passed.