# M03-RND-WMO-PLACEMENT-REGISTRY-001 — WMO placement registry

<!-- OPENWC_CLAIM:M03-RND-WMO-PLACEMENT-REGISTRY-001:sindo-main-codex:2026-07-20 -->

## Ownership

- Target: M03
- Program: RND
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m03-wmo-placement-registry`
- Lease expires UTC: 2026-07-20
- Integrator: M03 milestone integrator

## Outcome

Extract WMO placement-key to tile-reference ownership from the loader while
leaving every Node and renderer-resource lifecycle in the loader.

## Non-goals

- Change placement identity rules or WMO transforms.
- Move Node maps, world roots, tile state, jobs, queues or cancellation.
- Move cache/load requests, material refresh or render-group building.
- Change duplicate ordering, global-WMO lifetime or build budgets.
- Claim asset-backed WMO fidelity or performance acceptance.

## Paths

- Exclusive: `src/render/wmo/wmo_placement_registry.gd`,
  `src/tools/verify_wmo_placement_registry.gd`,
  `docs/modules/wmo-placement-registry.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
  `docs/modules/wmo-placement-resolver.md`, `docs/modules/world-renderer.md`,
  `docs/modules/README.md`, `RENDER.md`, `targets/03-renderer-facade.md`
- Generated/ignored: `.godot`, native DLL, generated ADT/WMO resources, caches
  and proprietary renderer corpus

## Contracts and data

- Input: resolved WMO placement key and tile/global reference key
- `add_reference` creates a key/ref set or idempotently retains an existing ref
- `release_reference` erases only the supplied ref and returns true only when the
  final ref removes the placement key
- `contains`, `active_count`, detached sorted diagnostics and idempotent `clear`
- Loader retains key→Node mapping and reacts to final release by cancelling the
  render build and queue-freeing the corresponding Node
- Cache/schema/coordinate/profile versions: unchanged

## Dependencies

- Requires: current master `5aa40d6`, `WmoPlacementResolver` identity contract
- Blocks: WMO build/resource state decomposition
- External state: none; tests use synthetic placement/tile keys

## Verification

- Commands: dedicated add/shared/idempotent/non-owner/final/global/clear/
  diagnostics/source/timing verifier; resolver/material/shutdown plus M2/terrain/
  facade/internal-access/manifest/scheduler/streaming/coordinate/docs/coord gates
- Fidelity evidence: exact shared-ref and final-release behavior preserved
- Performance budget: dictionary membership over active WMO keys/refs; no Node,
  Resource, RID, task, queue, mutex, cache or file access

## Documentation deliverables

- Inline registry API documentation
- New module spec with inputs/outputs, data-flow, lifecycle/state, ownership,
  failure/recovery, performance, fidelity limitations and source map
- Placement resolver, renderer/module registry and `RENDER.md` updates

## Simplicity and naming

- Important name: `WmoPlacementRegistry`
- Simplest solution: one private key-to-reference-set Dictionary
- Rejected complexity: generic ref-count registry, signals, callbacks, Resources,
  weak refs or Node ownership inside the service
- Unavoidable complexity: loader keeps a parallel key-to-Node map
- Measured optimization evidence: bounded synthetic add/release loop

## Status

- State: ready for integration
- Done: registry extracted; global/tile adapters migrated; Node/resource/job
  ownership retained in loader; contract, regressions, dry-run and docs passed
- Next: integrator merge and post-merge verification
- Blocked by:

## Handoff

- Commit: `c590036`
- Results: `verify_wmo_placement_registry.gd` PASS cases=10,
  iterations=100, elapsed_ms=53.941; 21 adjacent WMO/M2/terrain/facade/
  scheduler/streaming/coordinate regressions PASS; documentation and
  coordination gates PASS; render dry-run PASS 7/7.
- Remaining risks: no proprietary asset corpus or original-client paired WMO
  capture; dry-run reports expected missing ADT/DBC/character assets; WMO
  build/resource state remains loader-owned.
- Documentation updated: `docs/modules/wmo-placement-registry.md`,
  `docs/modules/wmo-placement-resolver.md`, `docs/modules/world-renderer.md`,
  `docs/modules/README.md`, `RENDER.md`; inline public API comments added.

<!-- OPENWC_HANDOFF_READY:M03-RND-WMO-PLACEMENT-REGISTRY-001:c590036 -->