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: 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:

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.