Migrate Iso/Lens to STAB form (Iso<S,T,A,B>)

[veewee]

Summary

Ports Iso and Lens from the two-template form (Iso<S, A> / Lens<S, A>) to the four-template profunctor "STAB" form (Iso<S, T, A, B> / Lens<S, T, A, B>), with:

• Concrete Iso / Lens classes invariant on all four slots. This is where compose boundary detection lives — standard Psalm template inference catches mismatches via invariant unification, no plugin hack needed. The AdjacentTemplateValidator workaround from Fix compose() boundary detection under covariant Iso/Lens templates #30 is deleted.
• IsoInterface / LensInterface covariant on all four slots. This is where storage flexibility lives — Iso<Person, Person, string, string> fits in IsoInterface<mixed, mixed, mixed, mixed> slots, so consumers can keep heterogeneous optics in a single collection without losing the leaf types. Same trade as C#'s IEnumerable<out T>.
• Type-changing API exposed. Lens::set(S, B): T, Iso::from(B): T, Lens::update(S, callable(A): B): T. Type-changing optics like Lens<Person, AnonymizedPerson, string, HashedName> are now expressible.

The DynamicFunctionStorage compose() providers (Iso + Lens) updated to emit 2N+2 templates with STAB pairing.

New docs (docs/stab-optics.md) walk a reader unfamiliar with optics through the four template slots with concrete Person / AnonymizedPerson / HashedName examples, the cheat sheet, and a "Footnote: a note on variance" explaining the concrete-vs-interface split.

BC

Hard break on the type level. Every Iso<S, A> / Lens<S, A> docblock callsite breaks. Runtime is source-compatible — method bodies are unchanged.

Bumps to 1.0.0, so the 0.x line stays compatible for consumers who can't migrate yet.

Verified

• composer cs:fix — clean
• composer psalm --no-cache — green
• vendor/bin/phpunit --no-coverage — 121 tests, 318 assertions
• Broken-composition SA tests still trip Incompatible types found for T3/T4 via standard inference (confirmed by temporarily flipping the @psalm-suppress).
• Cross-tested against a local php-soap/encoding branch consuming this; the interface-covariance choice unblocks its registry pattern without per-callsite casts.

Test plan

• composer cs:fix && composer psalm && vendor/bin/phpunit --no-coverage all green
• SA tests still catch boundary mismatches via invariant unification (no plugin hook)
• New SA tests in tests/static-analyzer/{Iso,Lens}/compose_type_changing.php exercise non-trivial S ≠ T and A ≠ B
• New unit tests exercise type-changing set / from end-to-end

[Copilot]

Pull request overview

This PR migrates the Iso and Lens optics from the 2-template form to the 4-template profunctor “STAB” form (<S, T, A, B>), enabling type-changing optics while relying on standard Psalm inference (via invariance) for compose-boundary detection, and removing the previous plugin workaround.

Changes:

• Port Iso/Lens and their interfaces to STAB generics, including type-changing APIs (set(): T, from(): T, update(): T).
• Update Psalm DynamicFunctionStorage compose providers to emit 2N+2 templates for STAB composition; remove AdjacentTemplateValidator.
• Add/adjust unit tests, static-analyzer tests, and documentation to explain STAB and validate type-changing composition.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/unit/Lens/LensTest.php	Adds a unit test covering type-changing Lens::set() behavior.
tests/unit/Iso/IsoTest.php	Adds a unit test covering type-changing Iso::from() behavior.
tests/static-analyzer/Lens/compose.php	Updates SA compose typing expectations to STAB templates and boundary-mismatch explanation.
tests/static-analyzer/Lens/compose_type_changing.php	Adds SA test for type-changing Lens composition (S≠T, A≠B).
tests/static-analyzer/Iso/compose.php	Updates SA compose typing expectations to STAB templates and boundary-mismatch explanation.
tests/static-analyzer/Iso/compose_type_changing.php	Adds SA test for type-changing Iso composition (S≠T, A≠B).
src/Psalm/Lens/Provider/ComposeProvider.php	Reworks compose signature generation to STAB chain (2N+2 templates).
src/Psalm/Iso/Provider/ComposeProvider.php	Reworks compose signature generation to STAB chain (2N+2 templates).
src/Psalm/Compose/AdjacentTemplateValidator.php	Removes the previous compose boundary validator workaround.
src/Lens/read_only.php	Updates STAB templates for read_only() wrapper return type.
src/Lens/property.php	Updates property() lens return type to STAB form.
src/Lens/properties.php	Updates properties() lens typing to STAB and adjusts getter closure.
src/Lens/optional.php	Updates optional() wrapper typing to STAB and to type-changing set (B→T).
src/Lens/LensInterface.php	Expands interface to STAB templates and type-changing methods/compose signature.
src/Lens/Lens.php	Expands concrete lens to STAB templates and updates method signatures accordingly.
src/Lens/index.php	Updates index() lens return type to STAB form.
src/Lens/compose.php	Updates compose function docs/typing to STAB.
src/Iso/object_data.php	Updates object_data() iso/accessor typing to STAB form.
src/Iso/IsoInterface.php	Expands interface to STAB templates and type-changing from()/compose signatures.
src/Iso/Iso.php	Expands concrete iso to STAB templates and updates method signatures accordingly.
src/Iso/compose.php	Updates compose function docs/typing to STAB.
README.md	Links to new STAB optics walkthrough doc.
docs/stab-optics.md	Adds new documentation explaining STAB optics, compose slot alignment, and variance tradeoffs.
docs/lens.md	Adds cross-link to the new STAB walkthrough.
docs/isomorphisms.md	Adds cross-link to the new STAB walkthrough.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.