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

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

## 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: ready-for-review
- Done: repository/reference audit, ADR, immutable value objects, pure mapper,
  build 12340/boundary/yaw fixtures, module specification and repository gates
- Next: integrator review and merge before renderer/native consumer migration
- Blocked by:

## Handoff

- Commit: `f45695c`
- Branch: `work/sindo-main-codex/m01-coordinate-mapper`
- Outcome: additive contract for canonical/server/ADT/Godot positions, ADT
  tile/chunk/local ownership and world-facing yaw; no existing consumer changed
- Public contracts: contract version 1 documented in
  `docs/modules/coordinate-mapping.md`; no persisted schema or cache change
- Verification: coordinate mapper PASS (5 golden points, 8 tile boundaries,
  5 yaw cases); M00 coordinate calibration PASS (5 points, maximum error
  `0.000015`); renderer manifest, coordination, documentation, dependency and
  whitespace checks passed; headless project load completed with expected
  missing proprietary-data diagnostics in the isolated worktree
- Fidelity: observed build 12340 positions match within `0.002` yard; formulas
  cross-checked against TrinityCore, OpenRealm and WoWee; visual parity is not claimed
- Migration/rebuild: none for this additive package; consumers migrate only
  after merge and must preserve renderer checkpoints
- Remaining risks: native loaders and renderer still use manual conversions;
  MDDF/MODF Euler mapping is intentionally unresolved; server-spawn integration
  and finite-value adapter validation remain later M01 packages
- Recommended merge order: this contract first, coordinate fixtures/server-spawn
  audit second, renderer/native consumers third, manual-conversion search gate last
- Documentation: ADR 0001; coordinate-mapping module spec with data-flow and
  dependency diagrams; inline API documentation on all public symbols