[Alexandre-T]

Pull Request

Closes #44

Summary

Consumers can now assemble and edit XYZ and XYZM polyhedral surfaces in place. Mutable PolyhedralSurface classes retain supplied polygon patches, rings and points by reference, support ordered patch and nested ring/point editing, and atomically replace complete coordinate content.

The implementation follows Epic #38 and Story #44. Dependencies #39, #40, #41 and #43 are merged. Mutable surfaces expose no with… methods or dimension setter. Immutable implementations remain separate.

Acceptance criteria

• All acceptance criteria are implemented.
• XYZ and XYZM classes live directly under their dimension namespace, with the final constructor family defaulting to Geometry.
• Zero-based patch, ring and point addressing, ordered membership, chaining and failure atomicity are covered.
• Shared instances retain identity; distinct equal-coordinate points remain independent. Immutable components, including descendants in custom mutable components, are rejected without conversion.
• Family, spatial-reference and SRID setters propagate recursively by default; false changes only the receiver. Coordinates, spatial type and layout remain unchanged.
• EMPTY and incomplete data and partially null ordinates remain representable without geometric validation or repair.

Validation

• Relevant tests pass.
• Repository quality checks pass.
• New tests cover editing, layouts, context propagation, shared vertices, immutable-source isolation and failure paths.

Commands run

vendor/bin/phpunit --no-coverage --filter MutablePolyhedralSurface
composer test-local
composer quality
php -d zend.assertions=1 -d assert.exception=1 /tmp/story44-example.php
git diff --cached --check

composer test-local: 920 tests, 8,468 assertions. The final suite includes 59 new surface tests. composer quality passed PHP CS Fixer, PHPStan level 9, PHPMD and PHPCS. Existing PHPMD/PDepend dependencies emit PHP 8.5 deprecation notices but no quality violation. The documentation example was executed with assertions enabled.

Standards

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

Normative references

ISO/IEC CD 13249-3:201x(E), Committee Draft dated 2009-01-16, clause 8.5.1 (ST_PolyhdrlSurface). The polygon-patch representation preserves the existing supported XYZ/XYZM layouts. Per the approved representation/validation boundary, face validity, adjacency, closure, manifold properties and context compatibility require explicit spatial-validator use; mutation performs no automatic validation, vertex synchronization or neighbouring-patch repair.

Architecture

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

Architecture decision

Epic #38 and Story #44: mutable and immutable implementations remain separate; mutable descendants are shared by reference, and coordinate arrays create mutable descendants. No new dependency or cross-library responsibility is introduced. MutablePolygonInterface::toArray() explicitly redeclares its existing coordinate-array read contract to preserve its precise PHPDoc return type when consumed through the aggregate interface.

Compatibility

• Public API changes were explicitly approved.
• No breaking change is introduced.
• Breaking changes were explicitly approved.

The new classes and type-specific mutable interface operations implement the approved Story #44 contract. Immutable constructors and copy APIs retain their behavior. No XY/XYM polyhedral surface, conversion, reprojection or factory change is included.

Documentation

• Documentation was updated where required.

docs/instantiable-spatial-types.md documents constructors, editing operations, ownership, addressing, propagation and a shared-vertex example. docs/immutability.md links the new contract; docs/type-class-hierarchy.md includes the mutable surface base and concrete classes.

Developer handoff

Important implementation decisions

Nested ring/point editing delegates to the retained mutable polygon; patch adoption checks every ring and point for mutable component ownership. Complete coordinate replacement hydrates all patches before assigning the new sequence, so a late technical failure leaves existing shared descendants untouched.

Remaining risks or questions

No unresolved Gate or blocking finding. Independent review concluded READY FOR MERGE for final SHA 04a02e3f3ae9807e9ff7d1a7d53ec0a7399a6ed4; PHP 8.4, PHP 8.5 and GitGuardian checks are successful for that revision. The final follow-up commit only clarifies the common indexing PHPDoc; immutable wrapping and mutable strict addressing remain unchanged. This PR is not merged and the Story remains In review.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.96907% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 99.45%. Comparing base (d0d711d) to head (04a02e3).
⚠️ Report is 13 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/Types/AbstractPolyhedralSurface.php	98.92%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #52      +/-   ##
============================================
+ Coverage     99.40%   99.45%   +0.04%     
- Complexity      703      933     +230     
============================================
  Files           132      170      +38     
  Lines          1525     2023     +498     
============================================
+ Hits           1516     2012     +496     
- Misses            9       11       +2     

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