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

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