coord(M03): claim entity presentation facade

coordination/claims/M03-RND-FACADE-ENTITY-001.md

@@ -0,0 +1,104 @@
+# 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`,
+  `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: