[Alexandre-T]

Pull Request

Closes #43

Summary

Add mutable Polygon and Triangle classes for XY, XYZ, XYM and XYZM. Consumers can edit ordered rings and points in place, replace complete coordinates, and propagate declared context without recalculating ordinates.

Acceptance criteria

• All acceptance criteria are implemented.
• Mutable components retain reference identity; immutable rings and points are rejected without conversion.
• Zero-based editing, insertion at count, chained return identity and failure atomicity are covered.
• All three context setters support recursive propagation by default and receiver-only updates with false.
• Open/incomplete rings, empty and partially-null points, and non-geometrically-valid triangles remain representable.
• Mutable and immutable contracts stay separate; spatial type and layout remain fixed.

Validation

• Relevant tests pass.
• Repository quality checks pass.

Commands run

vendor/bin/phpunit --no-coverage tests/Unit/Types/MutablePolygonTest.php tests/Unit/Types/MutablePolygonLayoutTest.php tests/Unit/Types/MutablePolygonContextTest.php
composer test-local
composer quality
git diff --check

The initial focused run passed 39 tests / 326 assertions. After additional edge cases, the complete suite passed 861 tests / 7,869 assertions, including 45 new tests. Coverage: 99.49% lines. Quality passed PHP CS Fixer, PHPStan level 9, PHPMD and PHP_CodeSniffer. PHPMD/PDepend dependencies emit PHP 8.5 deprecation messages; no quality violations remain. Local runtime: PHP 8.5.11.

Tests: MutablePolygonTest, MutablePolygonLayoutTest and MutablePolygonContextTest cover ownership, typed/nested rejection, ordering, ring and point failures, coordinate replacement isolation, every layout and recursive/local context changes.

Standards

• Applicable normative requirements were verified.
• A Normative Gate was required and resolved.

Normative references

ISO/IEC CD 13249-3:201x(E), clauses 8.3.1 (ST_Polygon, printed p. 294) and 8.4.1 (ST_Triangle, printed p. 311), inspected from the locally available 2009-01-16 Committee Draft. These define the geometry models. Under the approved #38/#43 representation contract, geometric validity remains an explicit spatial-validator concern; mutation does not close rings or enforce triangle cardinality. No new normative interpretation or serialization behavior is introduced.

Architecture

• The change follows an already approved architectural decision.
• An Architecture Gate was required and resolved.

Architecture decision

Apply #38/#39/#43: mutable concrete classes reside directly in their dimension namespaces, use a shared mutable ring-storage base, implement MutablePolygonInterface / MutableTriangleInterface, and expose no with-methods. Mutable objects do not extend immutable concrete classes.

Compatibility

• Public API changes were explicitly approved.
• No breaking change is introduced to the existing concrete implementations.
• Breaking changes were explicitly approved.

The already provisioned MutablePolygonInterface now defines the operations approved in #43 and narrows ring reads to MutableLineStringInterface. Consumers implementing that provisional interface must implement the new members. Immutable classes, factories, dependencies and supported runtimes are unchanged.

Documentation

• Documentation was updated where required.

Constructor signatures, mutation operations, ownership, propagation, indexing, atomicity and validity boundaries are documented in instantiable-spatial-types.md, with hierarchy and related reference updates.

Developer handoff

Important implementation decisions

All rings are hydrated and checked before complete replacement is committed. Typed component mutations validate addressing and mutable descendants before editing membership. Supplied rings/points are retained without cloning, while tuple input creates mutable descendants against the surface's current context.

Remaining risks or questions

Independent review and remote CI must be assessed separately. No unresolved product, API, architecture or normative decision was encountered. The PR must not be merged or the Story marked Done by the Developer.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.48%. Comparing base (d0d711d) to head (60fd333).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #51      +/-   ##
============================================
+ Coverage     99.40%   99.48%   +0.07%     
- Complexity      703      889     +186     
============================================
  Files           132      167      +35     
  Lines          1525     1926     +401     
============================================
+ Hits           1516     1916     +400     
- 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.