# 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: claimed
- Done: contract, ownership and non-goals published
- Next: implement snapshot, presenter, facade wiring, regressions and docs
- Blocked by:

## Handoff

- Commit:
- Results:
- Remaining risks:
- Documentation updated: