feat(mld): MLDv2 source-bearing state-change Reports (R4 P4a)

Emits the RFC 3810 §6.1 source-bearing MLDv2 state-change records on
multicast filter transitions — the IPv6 analogue of the shipped IGMPv3
source-state-change track, and the point where the source filters set via
the P2 MCAST_* socket options actually reach the wire.

New in the ICMPv6 TX handler:
- '_mld_state_change_records(group, old, new)' — the §6.1 difference
  table (the "non-listener" state is INCLUDE{}): a filter-mode change
  yields one CHANGE_TO_INCLUDE / CHANGE_TO_EXCLUDE record carrying the new
  source list; a within-mode source change yields ALLOW_NEW_SOURCES and/or
  BLOCK_OLD_SOURCES records (empty ones omitted). The IPv6 analogue of the
  IGMPv3 '_state_change_records'.
- '_send_mld_state_change(group, old, new)' — emits the aggregated MLDv2
  Report (type 143) to ff02::16, degrading to the coarse MLDv1 Report /
  Done keyed off the reception edge while in MLDv1 Host Compatibility Mode.
  The all-nodes group ff02::1 is never reported.
- '_emit_mld2_report(records)' — the shared assemble+send helper (a report
  with no records is not emitted).

The three edges of the multicast reception machinery now route through it:
the 'assign_ip6_multicast' join edge (old=INCLUDE{} nonmember, new=merged
filter), the 'remove_ip6_multicast' leave edge (old=filter, new=INCLUDE{}),
and the '_mc6_recompute' mid-membership delta (replacing the '# P4:'
placeholder). A source-specific join therefore now announces
ALLOW_NEW_SOURCES{src} / a mode flip announces CHANGE_TO_EXCLUDE with the
real source list, instead of the coarse all-groups current-state report
the join edge emitted before. The now-dead coarse '_send_icmp6_mld_leave'
(single-group) was removed — 'remove_ip6_multicast' supersedes it, and
'_send_mld_state_change' carries the MLDv1-Done fallback it held.

This is single immediate emission; the RFC 3810 §6.1 robustness
retransmit train (Robustness-Variable copies at random intervals) is P4b,
mirroring the v4 '_igmp_state_change__pending' / arm / fire / cancel
machinery. The §4.2 / §5.2 adherence flip waits for P4b + the P5 RX gate.

Tests-first: 'test__icmp6__mld__source_state_change.py' drives the
MCAST_* options through the socket and asserts the emitted MLDv2 records
carry the right type + source set (fresh join → ALLOW_NEW_SOURCES, second
source → ALLOW for the delta only, drop → BLOCK_OLD_SOURCES, block /
unblock on an any-source membership, INCLUDE→EXCLUDE mode flip →
CHANGE_TO_EXCLUDE), mirroring the IGMPv3 source-state-change tests. The
packet-handler / stack-init unit tests that mocked the old emit methods
now mock '_send_mld_state_change'.

Lint clean, 13534 passing, 0 skipped.

Reference: RFC 3810 §6.1 (source-bearing state-change Report difference records).
Reference: RFC 3810 §5.2.12 (ALLOW / BLOCK / CHANGE_TO record types).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ccie18643

docs/refactor/host_refinements_backlog.md

@@ -105,6 +105,16 @@ until the user says "push".
   `test__icmp6__mld__membership6_api.py` (8) + the join_group refcount /
   close tests. P4 (MLDv2 source records on the wire) + P5 (RX source-
   delivery gate) remain before the §4.2/§5.2 adherence flip.
+- [x] **IPv6 SSM state-change records (R4 P4a)** — MLDv2 source-bearing
+  state-change Reports on TX. New `_send_mld_state_change` /
+  `_mld_state_change_records` / `_emit_mld2_report` (the RFC 3810 §6.1
+  difference table + MLDv1 coarse fallback), wired to the join / leave /
+  mid-delta edges (a source-specific join now emits ALLOW_NEW_SOURCES /
+  BLOCK_OLD_SOURCES / CHANGE_TO_* with the real source list instead of the
+  coarse all-groups report); the dead coarse `_send_icmp6_mld_leave` was
+  removed. Single immediate emission — the §6.1 robustness retransmit train
+  is P4b. Tests: `test__icmp6__mld__source_state_change.py` (7). RFC 3810
+  §4.2/§5.2 adherence flip waits for P4b + P5.
 
 **The canonical SO_RCVBUF guard pattern** (mirror for any new datagram socket):
 
@@ -243,11 +253,23 @@ self._signal_readable()
     + the harness / thread-safety / ND-seed test updates. The RFC 3810
     §4.2 / §5.2 source-record adherence flip waits for P4/P5 (as the v4
     §3.2 flip waited for Phase 5).
-  - P4: MLDv2 source records on TX — `Icmp6Mld2MulticastAddressRecordType`
-    already has `ALLOW_NEW_SOURCES` (5) / `BLOCK_OLD_SOURCES` (6) /
-    `CHANGE_TO_INCLUDE` (3) / `CHANGE_TO_EXCLUDE` (4). Emit the state-change
-    source records on filter transitions (mirror `_send_igmp_state_change`;
-    the MLDv2 leave path added in `de3d3213` is the sibling to extend).
+  - **P4a — SHIPPED:** MLDv2 source-bearing state-change records on TX.
+    Added `_send_mld_state_change(group, old, new)` + `_mld_state_change_records`
+    (the §6.1 difference table: mode change → CHANGE_TO_INCLUDE /
+    CHANGE_TO_EXCLUDE with the new source list; within-mode source change →
+    ALLOW_NEW_SOURCES / BLOCK_OLD_SOURCES) + `_emit_mld2_report`, with the
+    MLDv1 coarse Report/Done fallback. Wired the three edges: the
+    `assign_ip6_multicast` join edge (`old=NONMEMBER, new`), the
+    `remove_ip6_multicast` leave edge (`old, new=NONMEMBER`), and the
+    `_mc6_recompute` mid-delta (replacing the `# P4:` placeholder). The now-
+    dead coarse `_send_icmp6_mld_leave` (single) was removed. Single
+    immediate emission — the RFC 3810 §6.1 robustness retransmit train is
+    **P4b** (mirror the v4 `_igmp_state_change__pending` /
+    `_arm`/`_fire`/`_cancel` machinery). Tests-first:
+    `test__icmp6__mld__source_state_change.py` (7) — ALLOW / BLOCK / TO_EX /
+    TO_IN records with source lists, mirroring the v4 track.
+  - P4b: the §6.1 robustness retransmit-train state machine
+    (`_mld_state_change__pending` + `_arm`/`_fire`/`_cancel`), mirror v4.
   - P5: RX source-delivery filter for IPv6 UDP + RAW (`Ip6MulticastFilter.allows`).
   - Adherence: update `docs/rfc/icmp6/rfc3810__mld2/adherence.md` (§4.2.12 /
     §5.1 / §5.2 source records) + a socket-parity note, in lockstep.
@@ -262,11 +284,13 @@ core (`_Ip6GroupMembership` / `_ip6_multicast_filters` / `_ip6_multicast_refs`
 / `mc6_*` / `_ip6_multicast_filter_for`, all under `_lock__multicast`) AND
 the socket surface (`stack.membership6`, refcounted `IPV6_JOIN_GROUP`, the
 `MCAST_*_SOURCE_*` family with `group_source_req`, per-socket
-`_ip6_source_filters`, close-time release) are done. **Remaining: P4**
-(`_send_mld_state_change` MLDv2 source records — ALLOW / BLOCK / CHANGE_TO_*
-— replacing the `# P4:` current-state-Report placeholder in `_mc6_recompute`
-and the join/leave edges), **P5** (RX `Ip6MulticastFilter.allows` source-
-delivery gate for UDP + RAW). After P4/P5 flip the RFC 3810 §4.2 / §5.2
+`_ip6_source_filters`, close-time release) are done. **P4a SHIPPED** — the
+`_send_mld_state_change` source-bearing state-change records (ALLOW / BLOCK /
+CHANGE_TO_*) now fire on all three edges (join / leave / mid-delta),
+single-emission. **Remaining: P4b** (the §6.1 robustness retransmit-train
+state machine — mirror the v4 `_igmp_state_change__pending` /
+`_arm`/`_fire`/`_cancel`), **P5** (RX `Ip6MulticastFilter.allows` source-
+delivery gate for UDP + RAW). After P4b/P5 flip the RFC 3810 §4.2 / §5.2
 adherence rows.
 
 - **Handler (`runtime/packet_handler/__init__.py`) — the deep, no-GIL-locked

packages/pytcp/pytcp/runtime/packet_handler/__init__.py

@@ -1094,12 +1094,11 @@ def _mc6_recompute(self, group: Ip6Address, /) -> None:
                     # §6.1 join Report.
                     self.assign_ip6_multicast(ip6_multicast=group)
                 elif merged != self._ip6_multicast_filters[group]:
-                    # Still joined, filter changed: re-materialize and
-                    # re-announce. P4: replace the current-state Report
-                    # with an MLDv2 ALLOW / BLOCK / CHANGE_TO_* source
-                    # delta ('_send_mld_state_change').
+                    # Still joined, filter changed: re-materialize and emit
+                    # the §6.1 source delta (ALLOW / BLOCK / CHANGE_TO_*).
+                    old = self._ip6_multicast_filters[group]
                     self._ip6_multicast_filters[group] = merged
-                    self._send_icmp6_multicast_listener_report()
+                    self._send_mld_state_change(group, old=old, new=merged)
             elif joined:
                 self.remove_ip6_multicast(ip6_multicast=group)
 
@@ -2754,13 +2753,20 @@ def _send_icmp6_multicast_listener_report(self) -> None:
 
         self._icmp6_tx._send_icmp6_multicast_listener_report()
 
-    def _send_icmp6_mld_leave(self, ip6_multicast: Ip6Address, /) -> None:
+    def _send_mld_state_change(
+        self,
+        group: Ip6Address,
+        /,
+        *,
+        old: Ip6MulticastFilter,
+        new: Ip6MulticastFilter,
+    ) -> None:
         """
-        Announce departure from an IPv6 multicast group (delegates to the
-        ICMPv6 TX sub-handler).
+        Emit an MLDv2 source-bearing state-change Report for 'group'
+        (RFC 3810 §6.1; delegates to the ICMPv6 TX sub-handler).
         """
 
-        self._icmp6_tx._send_icmp6_mld_leave(ip6_multicast)
+        self._icmp6_tx._send_mld_state_change(group, old=old, new=new)
 
     def _send_igmp_v3_report(self) -> None:
         """
@@ -3977,13 +3983,16 @@ def assign_ip6_multicast(self, /, ip6_multicast: Ip6Address) -> None:
             # Materialize the merged §4.2 reception filter (EXCLUDE{} for a
             # directly-assigned / any-source group, the merged contributors'
             # filter for a source-specific join).
-            self._ip6_multicast_filters[ip6_multicast] = self._ip6_multicast_filter_for(ip6_multicast)
+            new = self._ip6_multicast_filter_for(ip6_multicast)
+            self._ip6_multicast_filters[ip6_multicast] = new
 
             __debug__ and log("stack", f"Assigned IPv6 multicast {ip6_multicast}")
 
             self._assign_mac_multicast(ip6_multicast.multicast_mac)
 
-            self._send_icmp6_multicast_listener_report()
+            # RFC 3810 §6.1 — announce the new membership with a state-change
+            # Report describing the INCLUDE{}→'new' transition.
+            self._send_mld_state_change(ip6_multicast, old=_IP6_MULTICAST__NONMEMBER, new=new)
 
     @override
     def remove_ip6_multicast(self, /, ip6_multicast: Ip6Address) -> None:
@@ -3992,16 +4001,17 @@ def remove_ip6_multicast(self, /, ip6_multicast: Ip6Address) -> None:
         """
 
         with self._lock__multicast:
+            old = self._ip6_multicast_filters[ip6_multicast]
             del self._ip6_multicast_filters[ip6_multicast]
 
             __debug__ and log("stack", f"Removed IPv6 multicast {ip6_multicast}")
 
             self._remove_mac_multicast(ip6_multicast.multicast_mac)
 
-            # RFC 3810 §6.1 — announce the departure with a State Change
-            # Report (CHANGE_TO_INCLUDE, empty source list), the IPv6
-            # analogue of the IGMP leave above.
-            self._send_icmp6_mld_leave(ip6_multicast)
+            # RFC 3810 §6.1 — announce the departure with a state-change
+            # Report describing the 'old'→INCLUDE{} transition (no longer a
+            # listener).
+            self._send_mld_state_change(ip6_multicast, old=old, new=_IP6_MULTICAST__NONMEMBER)
 
     @override
     def _assign_ip4_multicast(self, /, ip4_multicast: Ip4Address) -> None:
@@ -4205,11 +4215,14 @@ def assign_ip6_multicast(self, /, ip6_multicast: Ip6Address) -> None:
         with self._lock__multicast:
             # Materialize the merged §4.2 reception filter (EXCLUDE{} for an
             # any-source group, the merged contributors' filter otherwise).
-            self._ip6_multicast_filters[ip6_multicast] = self._ip6_multicast_filter_for(ip6_multicast)
+            new = self._ip6_multicast_filter_for(ip6_multicast)
+            self._ip6_multicast_filters[ip6_multicast] = new
 
             __debug__ and log("stack", f"Assigned IPv6 multicast {ip6_multicast}")
 
-            self._send_icmp6_multicast_listener_report()
+            # RFC 3810 §6.1 — announce the new membership with a state-change
+            # Report describing the INCLUDE{}→'new' transition.
+            self._send_mld_state_change(ip6_multicast, old=_IP6_MULTICAST__NONMEMBER, new=new)
 
     @override
     def remove_ip6_multicast(self, /, ip6_multicast: Ip6Address) -> None:
@@ -4218,13 +4231,14 @@ def remove_ip6_multicast(self, /, ip6_multicast: Ip6Address) -> None:
         """
 
         with self._lock__multicast:
+            old = self._ip6_multicast_filters[ip6_multicast]
             del self._ip6_multicast_filters[ip6_multicast]
 
             __debug__ and log("stack", f"Removed IPv6 multicast {ip6_multicast}")
 
-            # RFC 3810 §6.1 — announce the departure with a State Change
-            # Report (CHANGE_TO_INCLUDE, empty source list).
-            self._send_icmp6_mld_leave(ip6_multicast)
+            # RFC 3810 §6.1 — announce the departure with a state-change
+            # Report describing the 'old'→INCLUDE{} transition.
+            self._send_mld_state_change(ip6_multicast, old=old, new=_IP6_MULTICAST__NONMEMBER)
 
     @override
     def _assign_ip4_multicast(self, /, ip4_multicast: Ip4Address) -> None:

packages/pytcp/pytcp/runtime/packet_handler/packet_handler__icmp6__tx.py

@@ -71,13 +71,23 @@
     Ip6HbhOptionRouterAlert,
 )
 from net_proto.protocols.ip6_hbh.options.ip6_hbh__options import Ip6HbhOptions
+from pytcp.lib.ip6_multicast_filter import (
+    Ip6MulticastFilter,
+    Ip6MulticastFilterMode,
+)
 from pytcp.lib.logger import log
 from pytcp.lib.tx_status import TxStatus
 from pytcp.stack import sysctl_iface
 
 if TYPE_CHECKING:
     from pytcp.runtime.packet_handler import PacketHandler
 
+# The IPv6 MLD destinations (RFC 3810 §5.2.14 / RFC 2710 §3): an MLDv2
+# Report goes to the all-MLDv2-routers group; the all-nodes group is
+# never reported (RFC 3810 §6).
+MLD__ALL_MLDV2_ROUTERS = Ip6Address("ff02::16")
+MLD__ALL_NODES = Ip6Address("ff02::1")
+
 
 class Icmp6TxHandler:
     """
@@ -263,41 +273,6 @@ def _send_icmp6_mld1_report(self, group: Ip6Address, /) -> None:
         self._if._packet_stats_tx.icmp6__mld1__report__send += 1
         self.__send_icmp6_mld_via_hbh_ra(icmp6_packet_tx, ip6__dst=group)
 
-    def _send_icmp6_mld_leave(self, group: Ip6Address, /) -> None:
-        """
-        Announce departure from a single IPv6 multicast group.
-
-        Reference: RFC 3810 §5.2.12 (CHANGE_TO_INCLUDE record).
-        Reference: RFC 3810 §6.1 (leaving a group is a state-change Report).
-
-        The all-nodes group (ff02::1) is never reported (RFC 3810 §6).
-        While in MLDv1 Host Compatibility Mode the departure is announced
-        with an MLDv1 Done so an MLDv1-only querier can parse it
-        (RFC 3810 §8.3.2); otherwise an MLDv2 State Change Report with a
-        CHANGE_TO_INCLUDE record and an empty source list is the leave
-        signal.
-        """
-
-        if group == Ip6Address("ff02::1"):
-            return
-
-        if self._if._mld_host_compatibility_mode() is MldVersion.V1:
-            self._send_icmp6_mld1_done(group)
-            return
-
-        icmp6_packet_tx = Icmp6Assembler(
-            icmp6__message=Icmp6Mld2MessageReport(
-                records=[
-                    Icmp6Mld2MulticastAddressRecord(
-                        type=Icmp6Mld2MulticastAddressRecordType.CHANGE_TO_INCLUDE,
-                        multicast_address=group,
-                    )
-                ],
-            ),
-        )
-        self._if._packet_stats_tx.icmp6__mld2__report__send += 1
-        self.__send_icmp6_mld_via_hbh_ra(icmp6_packet_tx, ip6__dst=Ip6Address("ff02::16"))
-
     def _send_icmp6_mld1_done(self, group: Ip6Address, /) -> None:
         """
         Send an MLDv1 Multicast Listener Done (type 132) for 'group'.
@@ -348,6 +323,111 @@ def _send_icmp6_mld_leave_all(self) -> None:
         self._if._packet_stats_tx.icmp6__mld2__report__send += 1
         self.__send_icmp6_mld_via_hbh_ra(icmp6_packet_tx, ip6__dst=Ip6Address("ff02::16"))
 
+    def _emit_mld2_report(self, records: list[Icmp6Mld2MulticastAddressRecord], /) -> None:
+        """
+        Assemble and emit a single aggregated MLDv2 State Change Report
+        (type 143) carrying 'records' to the all-MLDv2-routers group
+        ff02::16, wrapped in the Hop-by-Hop Router Alert carrier
+        (RFC 3810 §5.2.14). A report with no records is not emitted.
+        """
+
+        if not records:
+            return
+
+        icmp6_packet_tx = Icmp6Assembler(
+            icmp6__message=Icmp6Mld2MessageReport(records=records),
+        )
+        self._if._packet_stats_tx.icmp6__mld2__report__send += 1
+        self.__send_icmp6_mld_via_hbh_ra(icmp6_packet_tx, ip6__dst=MLD__ALL_MLDV2_ROUTERS)
+
+    @staticmethod
+    def _mld_state_change_records(
+        group: Ip6Address,
+        old: Ip6MulticastFilter,
+        new: Ip6MulticastFilter,
+        /,
+    ) -> list[Icmp6Mld2MulticastAddressRecord]:
+        """
+        Compute the MLDv2 difference records for a group's filter change
+        per the RFC 3810 §6.1 table (the "non-listener" state is
+        INCLUDE{}): a filter-mode change yields one CHANGE_TO_INCLUDE /
+        CHANGE_TO_EXCLUDE record carrying the new source list; a
+        within-mode source change yields ALLOW_NEW_SOURCES and/or
+        BLOCK_OLD_SOURCES records (empty ones are omitted). The IPv6
+        analogue of the IGMPv3 '_state_change_records'.
+        """
+
+        if old.mode is new.mode:
+            if old.mode is Ip6MulticastFilterMode.INCLUDE:
+                allow, block = new.sources - old.sources, old.sources - new.sources
+            else:
+                allow, block = old.sources - new.sources, new.sources - old.sources
+            records: list[Icmp6Mld2MulticastAddressRecord] = []
+            if allow:
+                records.append(
+                    Icmp6Mld2MulticastAddressRecord(
+                        type=Icmp6Mld2MulticastAddressRecordType.ALLOW_NEW_SOURCES,
+                        multicast_address=group,
+                        source_addresses=sorted(allow, key=int),
+                    )
+                )
+            if block:
+                records.append(
+                    Icmp6Mld2MulticastAddressRecord(
+                        type=Icmp6Mld2MulticastAddressRecordType.BLOCK_OLD_SOURCES,
+                        multicast_address=group,
+                        source_addresses=sorted(block, key=int),
+                    )
+                )
+            return records
+
+        record_type = (
+            Icmp6Mld2MulticastAddressRecordType.CHANGE_TO_EXCLUDE
+            if new.mode is Ip6MulticastFilterMode.EXCLUDE
+            else Icmp6Mld2MulticastAddressRecordType.CHANGE_TO_INCLUDE
+        )
+        return [
+            Icmp6Mld2MulticastAddressRecord(
+                type=record_type,
+                multicast_address=group,
+                source_addresses=sorted(new.sources, key=int),
+            )
+        ]
+
+    def _send_mld_state_change(
+        self,
+        group: Ip6Address,
+        /,
+        *,
+        old: Ip6MulticastFilter,
+        new: Ip6MulticastFilter,
+    ) -> None:
+        """
+        Emit an unsolicited state-change Report for 'group' describing the
+        transition from filter 'old' to filter 'new' (RFC 3810 §6.1) in
+        the form dictated by the interface's Host Compatibility Mode
+        (§8.3). In MLDv2 mode the Report carries the source-bearing §6.1
+        difference records; in MLDv1 mode it degrades to the coarse
+        Report / Done (MLDv1 has no source concept), keyed only off the
+        reception edge. The all-nodes group ff02::1 is never reported
+        (RFC 3810 §6). The IPv6 analogue of '_send_igmp_state_change'.
+        """
+
+        if group == MLD__ALL_NODES:
+            return
+
+        # The coarse MLDv1 form keys only off the reception edge — a
+        # source-only change within a still-joined membership is invisible
+        # to an older-version querier.
+        if self._if._mld_host_compatibility_mode() is MldVersion.V1:
+            if new.has_reception and not old.has_reception:
+                self._send_icmp6_mld1_report(group)
+            elif old.has_reception and not new.has_reception:
+                self._send_icmp6_mld1_done(group)
+            return
+
+        self._emit_mld2_report(self._mld_state_change_records(group, old, new))
+
     def __send_icmp6_mld_via_hbh_ra(self, icmp6_packet_tx: Icmp6Assembler, /, *, ip6__dst: Ip6Address) -> None:
         """
         Emit an MLD ICMPv6 message ('icmp6_packet_tx') wrapped in a