diff --git a/coordination/claims/M03-RND-M2-PLACEMENT-GROUPER-001.md b/coordination/claims/M03-RND-M2-PLACEMENT-GROUPER-001.md new file mode 100644 index 0000000..3686f92 --- /dev/null +++ b/coordination/claims/M03-RND-M2-PLACEMENT-GROUPER-001.md @@ -0,0 +1,93 @@ +# 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: