diff --git a/coordination/claims/M01-FND-COORD-BOUNDARY-GATE-001.md b/coordination/claims/M01-FND-COORD-BOUNDARY-GATE-001.md new file mode 100644 index 0000000..9a04300 --- /dev/null +++ b/coordination/claims/M01-FND-COORD-BOUNDARY-GATE-001.md @@ -0,0 +1,85 @@ +# M01-FND-COORD-BOUNDARY-GATE-001 — Coordinate conversion boundary gate + + + +## 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: active +- Done: repository audit and exception taxonomy +- Next: mapper extensions, consumer migration, enforcement gate and documentation +- Blocked by: