[Alexandre-T]

Pull Request

Closes #40

Summary

Add mutable Point classes directly under the XY, XYZ, XYM and XYZM namespaces. Coordinate, family and declared-reference setters retain object identity, preserve partial/null states, and reject unsupported axes or invalid input without mutating the receiver. Share existing point reads and geo-parser handling through an internal trait.

Acceptance criteria

• All Story Story: Edit point coordinates and declared spatial context in place #40 acceptance criteria are implemented.
• Constructor-compatible X/Y parsing, numeric/null Z/M input, fixed layouts, same-instance chaining, both families and reference-only changes are covered.
• Mutable points expose no immutable copy operations; immutable aggregate ownership contracts remain unchanged.

Validation

• Relevant tests pass: 734 tests, 6,859 assertions, including 44 new explicit mutable-point tests.
• Repository quality checks pass.
• Regression tests were added when fixing a bug. N/A: feature.

Commands run

composer test-local
composer quality
git diff --check

PHP 8.5.11 with PCOV 1.0.12. The complete quality command succeeds; installed PHPMD/PDepend dependencies emit PHP 8.5 deprecation notices. CI is green on PHP 8.4 and PHP 8.5; GitGuardian also passes. Independent review is READY FOR MERGE on f66c2e2: review.

Standards

• No normative spatial behavior is affected.

Normative references

The existing #36/#38 representation contract is preserved: accepting incomplete coordinates does not assert geometric conformity. No automatic validation, repair, reprojection or dimension conversion is added.

Architecture

• The change follows an already approved architectural decision.

Architecture decision

Follow Epic #38 and Story #39: shared read contracts, mutable concrete points beside family namespaces, instance family state, immutable auxiliary Coordinates and SpatialReference values, and no inheritance from concrete immutable types.

Compatibility

• Public API changes follow the explicit contracts approved in Epic: Support mutable and immutable spatial objects #38/Story: Edit point coordinates and declared spatial context in place #40.
• Existing immutable concrete behavior is preserved.

MutablePointInterface now requires four ordinate setters, as specified by #40; custom implementations must provide them. No additional breaking change or deprecated alias is introduced.

Documentation

• Documentation was updated where required.

Document constructors, mutation/input/error contracts, EMPTY states, reference changes and shared implementation hierarchy in the repository's public API documentation.

Developer handoff

Important implementation decisions

PointBehaviorTrait reuses existing reads and parsing unchanged. Each ordinate assignment completes parsing before changing state, then recomputes EMPTY. Metadata setters preserve ordinates. Coordinates returned before an edit remain immutable snapshots.

Compatibility considerations

Factories continue producing immutable variants; mutable aggregate editing belongs to later Stories.

Remaining risks or questions

Independent review is READY FOR MERGE on the current revision and CI is green. Awaiting Alexandre’s merge decision; no merge or Done transition is performed.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.54015% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.38%. Comparing base (d0d711d) to head (f66c2e2).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/Types/AbstractPoint.php	95.45%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #48      +/-   ##
============================================
- Coverage     99.40%   99.38%   -0.03%     
- Complexity      703      744      +41     
============================================
  Files           132      140       +8     
  Lines          1525     1633     +108     
============================================
+ Hits           1516     1623     +107     
- Misses            9       10       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Alexandre-T]

READY FOR MERGE

Independent review of commit f66c2e2 against Story #40, Epic #38, the merged #36/#39 contracts, repository instructions and the shared pre-merge Definition of Done.

No blocking findings or unresolved gates were identified. The four concrete mutable Point classes expose the approved namespace, constructor and interface contracts. Setters preserve identity, type and coordinate layout; null/EMPTY transitions, constructor-compatible X/Y parsing, numeric/null Z/M input, unavailable-axis exceptions and failure atomicity match the acceptance criteria. Declared family/reference edits preserve ordinates. Shared point behavior retains immutable copy semantics and immutable component ownership checks; no automatic geometric validation or transformation is introduced. Documentation covers the new public behavior.

Independently executed composer test-local: 734 tests, 6,859 assertions; composer quality: successful (PHP 8.5.11, installed PHPMD/PDepend dependency deprecation notices only). The working tree remains clean. Verified successful PHP 8.4, PHP 8.5 and GitGuardian checks on the reviewed SHA.

The explicit #38/#40 public API changes are within the approved scope; no new normative interpretation or architectural boundary change is introduced. There are no additional non-blocking findings. This review does not merge the PR or mark the Story Done; the maintainer's merge decision and post-merge verification remain outstanding.