# M03-RND-FACADE-ENTITY-001 — World entity presentation commands

<!-- OPENWC_CLAIM:M03-RND-FACADE-ENTITY-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-entity`
- Lease expires UTC: 2026-07-18
- Integrator: M03 milestone integrator

## Outcome

Add immutable, versioned world-entity presentation input and stable facade
commands for idempotent present/update and removal, backed by a renderer-owned
scene service with explicit entity subtree ownership.

## Non-goals

- Define authoritative entity/gameplay/network state or allocate/map identities.
- Move the local player controller/presenters behind the world-entity service.
- Implement build-12340 display IDs, equipment, animation, effects or visibility rules.
- Add background loading, pooling, MultiMesh conversion or a generic ECS/framework.
- Change streamer queues, caches, world assets, baseline visuals or target status.

## Paths

- Exclusive: `src/render/entities/entity_presentation_snapshot.gd`,
  `src/render/entities/world_entity_presenter.gd`,
  `src/tools/verify_world_entity_presentation.gd`,
  `src/tests/scenes/world_entity_visual_replacement_fixture.tscn`,
  `docs/modules/world-entity-presentation.md`, this claim
- Shared/hotspots: `src/render/world_render_facade.gd`, both runtime streaming
  scenes, `src/tools/verify_world_render_facade.gd`, `docs/modules/world-renderer.md`,
  `docs/modules/README.md`, `RENDER.md`, `targets/03-renderer-facade.md`
- Reused unchanged: `EntityId`, `GodotWorldPosition`, existing asset-free
  character presentation model fixture
- Generated/ignored: `.godot`, native DLL, generated resources, caches and
  proprietary renderer corpus

## Contracts and data

- Contract version: `EntityPresentationSnapshot.CONTRACT_VERSION = 1`
- Snapshot: valid session-local `EntityId`, typed Godot world position, visual
  PackedScene path, finite yaw radians, positive finite uniform scale and visibility
- Public API: `WorldRenderFacade.present_entity`, `remove_entity`,
  `entity_presentation_snapshot`
- Presenter behavior: present is idempotent by entity key; same visual updates
  transform/visibility, changed visual replaces the owned subtree; remove is explicit
- Schema/cache/coordinate contracts: no persisted schema or cache change

## Dependencies

- Requires: integrated M03 environment facade master `a85e416`, M01 identity and
  coordinate contracts
- Blocks: completion of the first M03 facade checklist item and later entity renderer extraction
- External state: none; tests use a repository-owned asset-free PackedScene fixture

## Verification

- Commands: cold snapshot contract; presenter lifecycle/ownership regression;
  facade delegation and runtime wiring; identity/coordinate/internal-access;
  renderer manifest/shutdown/planner/scheduler/focus and repository gates
- Fixtures: invalid identity/position/yaw/scale/path, spawn, idempotent update,
  visual replacement, missing asset, removal, detached diagnostic snapshot and teardown
- Fidelity evidence: no runtime commands are produced yet, so existing scene output
  and seven baseline plans remain unchanged
- Performance budget: constant-time entity lookup; synchronous resource load only
  on first presentation/visual replacement and explicitly excluded from hot-path acceptance

## Documentation deliverables

- Inline public API docs: snapshot, facade commands and presenter lifecycle
- Module specification: new world-entity-presentation specification
- Data-flow diagram: read model through facade into owned visual subtree
- Sequence/state/dependency diagrams: present/update/replace/remove/failure/teardown
- Source map/status updates: module registry, world renderer and `RENDER.md`

## Simplicity and naming

- Important names introduced: `EntityPresentationSnapshot`, `WorldEntityPresenter`,
  `present_entity`, `remove_entity`
- Simplest considered solution: one immutable full visual snapshot and one
  dictionary-owned Node3D presenter below an explicit scene service
- Rejected complexity/abstractions: ECS, event bus, command hierarchy, factory
  registry, pooling, async loader framework or duplicate identity registry
- Unavoidable complexity and justification: renderer must own and deterministically
  replace/free visual subtrees while authoritative state remains external
- Measured optimization evidence: no optimization claim; lifecycle is asset-free tested

## Status

- State: ready-for-review
- Done: immutable contract-v1 snapshot, presenter ownership lifecycle, facade
  commands, runtime composition, asset-free regressions and module documentation
- Next: M03 integrator reviews and merges `1807c3a`
- Blocked by:

<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-ENTITY-001:1807c3a -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-FACADE-ENTITY-001:606770c -->

## Handoff

- Commit: `1807c3a`
- Results: facade now exposes idempotent `present_entity`, explicit
  `remove_entity` and detached diagnostics. Both runtime scenes compose a
  `WorldEntityPresenter` that owns one replaceable visual subtree per valid
  session `EntityId`; local player and authoritative state remain separate.
- Verification: entity `snapshot_cases=8 lifecycle_cases=14 runtime_scenes=2`;
  facade `delegation=9 entity_contract=6`; identities `5/5/6/5`; character
  presentation `9/10/3/1`; coordinate boundary `files=119`; internal access
  `43/7/9/1`; environment/ground/terrain, manifest `7/7`, shutdown, scheduler
  (`20000` iterations), planner (`250` iterations), focus, editor parse, dry-run,
  coordination, documentation and diff gates passed.
- Fidelity: runtime produces no world-entity commands yet, so all seven baseline
  plans and existing player/world output remain unchanged. No build-12340
  display, equipment, animation, effects or visibility parity claim is added.
- External/local inputs: ignored native DLL and generated ADT scripts supported
  editor/dry-run only. Missing proprietary ADT/DBC/character corpus produced the
  expected degraded diagnostics.
- Remaining risks: PackedScene create/replace loads synchronously and is not an
  accepted network-scale hot path; resource paths are adapter inputs rather than
  stable content IDs; animation/equipment/effects and scale profiling remain open.
- Documentation updated: new world-entity-presentation API/input-output/data-flow/
  lifecycle/sequence/ownership/failure/configuration/migration/diagnostic/source-map
  spec; world renderer, module registry and `RENDER.md` updated.
- Integration: accepted in master merge `606770c`; post-merge entity/facade,
  character, internal-access, manifest, shutdown, scheduler and planner gates passed.
