Detect embedding strategies and extract the address

[zanbaldwin]

The IpInterface declarations are deprecated in favour of StrategyDetectionInterface

[greptile-apps]

Greptile Summary

This PR adds strategy-based embedded IPv4 detection for IPv6-capable address types. The main changes are:

• New experimental StrategyDetectionInterface for strategy predicates and embedded IPv4 extraction.
• IPv6 and Multi implementations for mapped, derived, compatible, NAT64, and Teredo detection.
• getEmbeddedIp() support with default, instance, and explicit strategy behavior.
• Deprecated legacy embedding predicates on IpInterface while keeping compatibility.
• Updated docs, changelog, and tests for the new detection API.

Confidence Score: 5/5

Safe to merge with minimal risk.

The changes are focused and preserve compatibility with deprecated interface methods. New tests cover IPv4, IPv6, and Multi behavior for the added strategy detection paths. No blocking correctness or security issues were identified.

No files require special attention.

T-Rex Logs

What T-Rex did

• Ran the pre-change strategy-detection contract check to establish the baseline state, confirming that StrategyDetectionInterface was absent, IPv6 and Multi were not instances, and the new methods were missing; getEmbeddedIp and isEmbeddedAccordingToStrategy failed on the base, while mapped/derived/compatible predicates still returned true.
• Ran the post-change checks after implementing StrategyDetectionInterface and related updates, confirming that StrategyDetectionInterface exists, IPv6 and Multi are now instances, IPv4 is not, and the embedded predicate docs are deprecated; the new methods exist.
• Verified NAT64 and Teredo classifications succeed and that the generic Derived detection returns true.
• Verified embedded extraction returns 127.0.0.1 and non-embedded extraction reports WrongVersionException.
• Noted the proof files used to validate the before/after states: trex-artifacts/strategy-detection-contract-01-before.txt and trex-artifacts/strategy-detection-contract-02-after.txt.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/Contracts/StrategyDetectionInterface.php	Introduces the experimental strategy detection contract for IPv6-capable implementations.
src/Version/IPv6.php	Implements strategy detection, NAT64/Teredo predicates, embedded IPv4 extraction, and reuses them in global reachability checks.
src/Version/Multi.php	Keeps instance-strategy-based embedding detection and adds embedded IPv4 extraction with explicit strategy override support.
src/AbstractIP.php	Changes base deprecated embedding predicates to return false for classes that do not override strategy detection.
src/Version/Version6Interface.php	Extends IPv6 contracts with the new strategy detection interface.
tests/Version/IPv6Test.php	Adds IPv6 coverage for generic strategy detection, NAT64/Teredo predicates, and embedded IPv4 extraction behavior.
tests/Version/MultiTest.php	Adds Multi coverage for instance/default strategy extraction and strategy-specific embedded address behavior.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Caller
participant IPv6
participant Multi
participant Strategy
participant IPv4

Caller->>IPv6: getEmbeddedIp(strategy?)
alt explicit strategy supplied
    IPv6->>Multi: fromBinary(binary, strategy)
else no strategy supplied
    IPv6->>Multi: fromBinary(binary, default strategy)
end
IPv6->>Multi: getEmbeddedIp()
Multi->>Strategy: isEmbedded(binary)
alt embedded according to strategy
    Multi->>Strategy: extract(binary)
    Multi->>IPv4: fromBinary(extracted)
    IPv4-->>Caller: embedded IPv4
else not embedded
    Multi-->>Caller: WrongVersionException
end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Caller
participant IPv6
participant Multi
participant Strategy
participant IPv4

Caller->>IPv6: getEmbeddedIp(strategy?)
alt explicit strategy supplied
    IPv6->>Multi: fromBinary(binary, strategy)
else no strategy supplied
    IPv6->>Multi: fromBinary(binary, default strategy)
end
IPv6->>Multi: getEmbeddedIp()
Multi->>Strategy: isEmbedded(binary)
alt embedded according to strategy
    Multi->>Strategy: extract(binary)
    Multi->>IPv4: fromBinary(extracted)
    IPv4-->>Caller: embedded IPv4
else not embedded
    Multi-->>Caller: WrongVersionException
end

Loading

_{Reviews (2): Last reviewed commit: "refactor(contracts): 🔨 deprecate embedd..." | Re-trigger Greptile}