open-wc/coordination/claims/M01-FND-COORD-BOUNDARY-GATE-001.md

# M01-FND-COORD-BOUNDARY-GATE-001 — Coordinate conversion boundary gate

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

## Ownership

- Target: M01
- Program: FND/QAR
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m01-coordinate-boundary-gate`
- Lease expires UTC: 2026-07-15
- Integrator: M01 milestone integrator

## Outcome

Route remaining GDScript world/tile axis conversions through `CoordinateMapper`
and add a repository-wide gate that rejects new manual world-center, axis-swap
or world-to-ADT tile formulas outside explicit contract/native-oracle boundaries.

## Non-goals

- Rewriting model-local M2/WMO vertex or placement orientation transforms.
- Moving renderer distance/LOD geometry out of Godot space.
- Replacing the native parser boundary with GDScript calls from worker threads.
- Changing coordinate contract semantics, renderer radii or cache formats.

## Paths

- Exclusive: `src/tools/verify_coordinate_conversion_boundaries.gd`
- Shared/hotspots: `src/domain/coordinates/coordinate_mapper.gd`, coordinate
  tests/docs/ADR, streamer/player/sky/terrain-probe consumers,
  `docs/CODING_STANDARD.md`, this claim
- Generated/ignored: Godot import metadata, extracted assets and renderer caches

## Contracts and data

- Additive mapper methods: Godot position to ADT tile/local and ADT tile/local
  to Godot position
- Native exception: one formula definition in `src/native/src/wow_chunk_reader.h`;
  ADT/WDT loaders may call it but may not define copies
- Oracle exception: `verify_render_coordinate_calibration.gd` retains one
  independent M00 formula to detect common-mode mapper regressions
- Model-local transforms are outside the world-coordinate gate

## Dependencies

- Requires: coordinate contract v2 and M01 seams through `7c64e8d`
- Blocks: M01 coordinate-centralization exit criterion and milestone evidence audit
- External state: no dependency or proprietary input

## Verification

- Commands: conversion-boundary gate, mapper/golden fixtures, streaming focus,
  identities, renderer calibration/manifest and repository gates
- Fixtures: Godot/ADT tile center, local offsets and exact boundaries
- Fidelity evidence: existing build-12340 points and raw ADT/server fixture remain unchanged
- Performance budget: mapper allocations occur only at adapter/update boundaries;
  renderer distance/LOD math remains in Godot scalars

## Documentation deliverables

- Inline public API docs: new mapper methods
- Module specification/ADR: boundary APIs, allowed exceptions and gate behavior
- Coding standard: mandatory review rule for cross-space conversions
- Data-flow diagram: existing coordinate module diagram updated for direct adapters
- State/sequence diagrams: unchanged; pure synchronous mapping

## Simplicity and naming

- Important names introduced: `godot_to_adt_tile`, `godot_to_adt_tile_local`,
  `adt_tile_local_to_godot`, `verify_coordinate_conversion_boundaries`
- Simplest considered solution: extend the existing mapper and scan source text
  for narrow high-signal formula signatures
- Rejected complexity/abstractions: generic coordinate algebra framework,
  native-to-GDScript calls on parser workers and a broad numeric-literal ban
- Unavoidable complexity and justification: one native boundary and one
  independent test oracle must remain explicit to avoid worker coupling and common-mode tests
- Measured optimization evidence: existing renderer distance/LOD scalar math is unchanged

## Status

- State: ready-for-review
- Done: mapper extensions, consumer migration, repository gate, review rule,
  integrated renderer gate, regression fixtures and documentation
- Next: integrator review, merge and M01 completion-evidence audit
- Blocked by:

## Handoff

- Commit: `47dec6c`
- Branch: `work/sindo-main-codex/m01-coordinate-boundary-gate`
- Outcome: all audited GDScript world/tile conversions in sky, streaming,
  player spawn/ground sampling and terrain probes route through typed
  `CoordinateMapper` boundaries. A repository scan rejects new manual
  world-center, legacy axis-conversion, world-to-tile, tile-local and
  tile-center formulas.
- Contract/schema: additive `godot_to_adt_tile`,
  `godot_to_adt_tile_local` and `adt_tile_local_to_godot` APIs; no persisted
  format, cache version or renderer radius changes.
- Verification: CoordinateConversionBoundaries PASS (`83` files, one native
  boundary, one independent oracle, four consumers, six classifier guards);
  CoordinateMapper PASS (`5` golden points, `8` tile boundaries, `2` raw MCNK,
  `5` yaw cases); renderer calibration PASS (`5` points, maximum error
  `0.000015`); renderer manifest PASS (`7/7/7`); unified render baseline dry-run,
  headless project load, runtime cache shutdown, coordination, documentation
  and whitespace gates passed.
- GUI regression: final ADT-boundary capture compared `2/2`, missing `0`,
  failed `0` (cold mean `0.0002324`, changed ratio `0.0013741`; warm mean
  `0.0000226`, changed ratio `0.0001285`). Earlier full capture produced all
  `14` images; `11/14` met the strict changed-pixel threshold. The three
  threshold-only differences retained low mean error (`<= 0.00622`) and were
  visually classified as cold M2 readiness and liquid animation phase, with
  unchanged camera, geometry alignment, area and streaming focus.
- Fidelity: existing build-12340 calibrated points, raw ADT fixture and server
  spawn fixture remain unchanged. Native parser workers retain exactly one
  formula in `wow_chunk_reader.h`; the calibration verifier retains exactly one
  independent formula so mapper and oracle cannot share a common-mode defect.
- Rebuild: none. Local ignored extracted assets/native binary/cache junctions
  were used for runtime checks and are not part of the commit.
- Remaining risks: source scanning intentionally recognizes narrow high-signal
  formula signatures rather than parsing arbitrary algebra; native formula
  parity still relies on calibration/raw fixtures. Model-local M2/WMO basis
  transforms and Godot-space LOD distance math are intentionally outside scope.
- Recommended merge order: after `7c64e8d`; this package closes the remaining
  M01 manual axis-conversion checklist item, but only the milestone integrator
  may update target Evidence/status or set `OPENWC_TARGET_DONE`.
- Documentation: coding review rule, coordinate-mapping module API/input-output/
  data-flow/capability/risk/source-map sections, ADR 0001 and `RENDER.md` were
  updated. Existing pure synchronous data-flow diagram remains authoritative;
  no state/sequence diagram changed.