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, 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: claimed
• Done: boundary, exact preservation rules and ownership published
• Next: implement grouper, migrate worker callback, tests and docs
• Blocked by:

Handoff

• Commit:
• Results:
• Remaining risks:
• Documentation updated: