diff --git a/coordination/claims/M01-FND-COORDS-001.md b/coordination/claims/M01-FND-COORDS-001.md new file mode 100644 index 0000000..a8a15b9 --- /dev/null +++ b/coordination/claims/M01-FND-COORDS-001.md @@ -0,0 +1,85 @@ +# M01-FND-COORDS-001 — Canonical coordinate contracts + + + +## Ownership + +- Target: M01 +- Program: FND +- Owner/Agent ID: sindo-main-codex +- Branch: `work/sindo-main-codex/m01-coordinate-mapper` +- Lease expires UTC: 2026-07-15 +- Integrator: M01 milestone integrator + +## Outcome + +Introduce scene-free value objects for canonical WoW, server, ADT placement, +ADT tile/chunk/local and Godot world coordinate spaces, plus the single pure +`CoordinateMapper` contract for position and world-yaw conversions. + +## Non-goals + +- Migrating `StreamingWorldLoader`, native parsers, sky, player or renderer code. +- Defining model-specific MDDF/MODF Euler rotation corrections. +- Introducing `StreamingFocus`, typed IDs or a test framework dependency. +- Claiming visual parity from arithmetic round trips. + +## Paths + +- Exclusive: `src/domain/coordinates/**`, `src/tools/verify_coordinate_mapper.gd`, + `docs/modules/coordinate-mapping.md`, `docs/adr/0001-canonical-world-coordinates.md` +- Shared/hotspots: `docs/modules/README.md`, this claim +- Generated/ignored: Godot import metadata and local test output + +## Contracts and data + +- Public API/events: immutable coordinate value objects and pure mapper methods +- Schema/format version: no persisted format; contract version 1 in module docs +- Migration/compatibility: additive contract; existing renderer conversions remain + unchanged until a later consumer migration package +- Consumers: future renderer, network, gameplay and server-data adapters +- Rollout order: contract and fixtures first, then native/parser and renderer consumers + +## Dependencies + +- Requires: merged M00 build 12340 coordinate calibration evidence +- Blocks: M01 renderer coordinate migration and `StreamingFocus` +- External state: no proprietary inputs; reference formulas are source-only evidence + +## Verification + +- Commands: headless coordinate contract probe, headless project load, + coordination and documentation gates +- Fixtures: five build 12340 camera points, ADT map center/edge/boundary points, + server/ADT/Godot round trips and yaw normalization cases +- Fidelity evidence: M00 observed build 12340 positions plus independent + OpenRealm/WoWee and TrinityCore grid formulas +- Performance budget: constant-time scalar arithmetic with no allocation beyond result values + +## Documentation deliverables + +- Inline public API docs: every public value object and mapper method +- Module specification: purpose, public API, inputs/outputs, ownership, errors and source map +- Data-flow diagram: server/ADT/canonical/Godot mappings +- Dependency diagram: canonical contract consumers and forbidden scene dependency +- Sequence/state diagrams: not applicable; mapper is synchronous and stateless +- ADR: coordinate axes, units, tile indexing and compatibility rollout + +## Simplicity and naming + +- Important names introduced: `CanonicalWowWorldPosition`, `ServerWorldPosition`, + `AdtPlacementPosition`, `AdtTileCoordinate`, `AdtChunkCoordinate`, + `AdtTileLocalPosition`, `GodotWorldPosition`, `WorldYaw`, `CoordinateMapper` +- Simplest considered solution: scalar immutable value objects and one pure mapper +- Rejected complexity/abstractions: generic vector-space framework, matrices, + dependency injection and a third-party test framework +- Unavoidable complexity and justification: distinct source spaces prevent silent axis swaps +- Measured optimization evidence: not applicable + +## Status + +- State: active +- Done: repository/reference audit and contract scope +- Next: ADR, fixtures, value objects and mapper implementation +- Blocked by: +