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

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

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: