# M01-FND-COORDS-001 — Canonical coordinate contracts

<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-15 -->

## 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: