diff --git a/coordination/claims/M03-RND-WMO-PLACEMENT-REGISTRY-001.md b/coordination/claims/M03-RND-WMO-PLACEMENT-REGISTRY-001.md new file mode 100644 index 0000000..8bbbed2 --- /dev/null +++ b/coordination/claims/M03-RND-WMO-PLACEMENT-REGISTRY-001.md @@ -0,0 +1,92 @@ +# M03-RND-WMO-PLACEMENT-REGISTRY-001 — WMO placement registry + + + +## 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: claimed +- Done: lifecycle, return semantics and ownership split published +- Next: implement registry, migrate global/tile adapters, tests and docs +- Blocked by: + +## Handoff + +- Commit: +- Results: +- Remaining risks: +- Documentation updated: