open-wc/coordination/claims/M03-RND-M2-PLACEMENT-GROUPER-001.md

M03-RND-M2-PLACEMENT-GROUPER-001 — M2 placement grouper

Ownership

• Target: M03
• Program: RND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m03-m2-placement-grouper
• Lease expires UTC: 2026-07-19
• Integrator: M03 milestone integrator

Outcome

Extract pure ADT M2 placement validation, path normalization and local-transform grouping from the worker callback into a scene-free service.

Non-goals

• Change placement ordering, coordinate conversion, transform formulas or clamps.
• Move WorkerThreadPool tasks, mutex/result queues, tile state or retry behavior.
• Move build jobs, animation/mesh loading, caches, Nodes, MultiMesh or RIDs.
• Generalize grouping policy, change batching or add a dependency.
• Claim build-12340 placement or visual parity beyond preserved formulas.

Paths

• Exclusive: src/render/m2/m2_placement_grouper.gd, src/tools/verify_m2_placement_grouper.gd, docs/modules/m2-placement-grouper.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, src/tools/verify_m2_placement_transform_resolver.gd, docs/modules/m2-placement-transform-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 resources, caches and proprietary renderer corpus

Contracts and data

• Input: tile-local origin, MMDX name table and raw ADT M2 placement array
• Output: fresh Dictionary keyed by historically normalized relative M2 path; each value is a fresh ordered Array of tile-local Transform3D values
• Invalid variants, out-of-range name IDs and empty paths are skipped
• Backslashes become slashes; lowercase .mdx/.mdl suffixes become .m2
• Transform basis/origin delegates to M2PlacementTransformResolver; final basis scale retains the grouping-path clamp max(scale, 0.0001)
• Cache/schema/coordinate versions: unchanged

Dependencies

• Requires: current master c34e538, M2PlacementTransformResolver
• Blocks: broader M2 worker/build decomposition
• External state: none; tests use synthetic names and placement dictionaries

Verification

• Commands: dedicated invalid/name/path/group-order/default/transform/scale and bounded timing verifier; loader source boundary; resolver/registry/dedupe plus facade/internal-access/manifest/shutdown/documentation/coordination gates
• Fidelity evidence: exact loop rules and transform composition moved unchanged
• Performance budget: linear over placement count with fresh output containers; no Node, Resource, RID, task, mutex, cache or file access

Documentation deliverables

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

Simplicity and naming

• Important name: M2PlacementGrouper
• Simplest solution: one stateless group_placements query
• Rejected complexity: group/result classes, strategy interfaces, callbacks, Resources, policies or generic spatial batching framework
• Unavoidable complexity: raw ADT dictionaries remain at the parser adapter
• Measured optimization evidence: bounded synthetic grouping loop

Status

• State: accepted
• Done: pure grouper, worker adapter, regressions and documentation verified
• Next: M2 worker/build state extraction and spatial-cell evidence
• Blocked by:

Handoff

• Commit: 9df32d3 (refactor(M03): extract M2 placement grouper)
• Results: dedicated grouper PASS (cases=9, iterations=100, placements=256, elapsed_ms=67.736); transform resolver PASS (cases=9, iterations=10000, elapsed_ms=28.571); M2 registry/dedupe, terrain cache/LOD/queue, facade, internal-access, manifest, shutdown, scheduler, streaming planner/focus, terrain-query and coordinate-boundary suites PASS; editor import parsed the project with only expected missing private corpus diagnostics; documentation PASS (module_specs=17, required_files=7); coordination PASS with 23 pre-existing expired M00/M01 warnings; checkpoint dry-run planned 7/7.
• Remaining risks: no private asset-backed traversal/visual comparison; uppercase extension preservation is historical but inconsistent with the resolver's case-insensitive exception matching; grouping remains model-path based rather than spatial-cell based; worker/build state and p95/p99 remain.
• Documentation updated: inline public API; new docs/modules/m2-placement-grouper.md; transform resolver module spec, renderer module registry, docs/modules/world-renderer.md and RENDER.md.
• Integration: accepted in master merge f88bf97; post-merge grouper (cases=9, iterations=100, placements=256, elapsed_ms=67.104), transform resolver, registry, internal-access, facade, manifest, documentation and coordination gates passed.