Fix ADR-0025: IPCQ direction addressing via address-based matching

2-rank bidirectional ring deadlock: when E and W neighbors point to the
same peer, sender-coord matching in _handle_meta_arrival / _credit_worker
picked the first direction in dict order, landing data in the wrong rx
slot relative to what the kernel recv(W) was waiting on.

Fix (ADR-0025 D1/D2/D3):
- install.reverse_direction: prefer OPPOSITE direction (E↔W, N↔S) when
  peer has it pointing back to us; fallback to any matching for
  topologies without opposite convention (tree_binary parent/child).
- _handle_meta_arrival: match by token.dst_addr range against each qp's
  my_rx_base_pa + n_slots × slot_size window (unambiguous).
- _credit_worker: match by credit.dst_rx_base_pa == qp.peer.rx_base_pa.
- IpcqCreditMetadata: new dst_rx_base_pa field carrying receiver-side
  rx base; _delayed_credit_send fills it from the consuming qp.

Tests (Phase 1 → Phase 2):
- test_reverse_direction_opposite_preference_2rank_ring
- test_reverse_direction_opposite_preference_4rank_ring_sanity
- test_meta_arrival_matches_by_dst_addr_same_peer
- test_credit_matches_by_dst_rx_base_pa_same_peer
- Existing credit-return test updated with dst_rx_base_pa.

508 tests pass.

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

src/kernbench/ccl/install.py

@@ -219,9 +219,24 @@ def install_ipcq(
         "neighbor_table": neighbor_table,
     }
 
-    def reverse_direction(my_rank: int, peer_rank: int) -> str | None:
-        """Find which direction in peer's neighbor table points back to my_rank."""
-        for d, target in neighbor_table[peer_rank].items():
+    _OPPOSITE_DIR = {"E": "W", "W": "E", "N": "S", "S": "N"}
+
+    def reverse_direction(my_rank: int, peer_rank: int, my_dir: str) -> str | None:
+        """Find peer's direction that reciprocates my_dir→peer_rank.
+
+        Prefer the OPPOSITE direction (E↔W, N↔S) when the peer has it
+        pointing back to us (ADR-0025 D1). This matters in 2-rank
+        bidirectional rings where both E and W on one side point to the
+        same peer — without the preference, dict-order first-match would
+        route data into the wrong rx slot. Falls back to any direction
+        pointing back for topologies without an opposite convention
+        (e.g. tree_binary's parent/child).
+        """
+        nt = neighbor_table[peer_rank]
+        opp = _OPPOSITE_DIR.get(my_dir)
+        if opp is not None and nt.get(opp) == my_rank:
+            return opp
+        for d, target in nt.items():
             if target == my_rank:
                 return d
         return None
@@ -234,7 +249,7 @@ def install_ipcq(
             if peer_rank is None:
                 continue
             peer_s, peer_c, peer_p = rank_pe[peer_rank]
-            peer_dir = reverse_direction(r, peer_rank)
+            peer_dir = reverse_direction(r, peer_rank, d)
             if peer_dir is None:
                 # Peer doesn't have a reverse entry — skip (asymmetric topology)
                 continue

src/kernbench/common/ipcq_types.py

@@ -196,10 +196,17 @@ class IpcqCreditMetadata:
     Sent by ``PeIpcqComponent._delayed_credit_send`` after a
     bottleneck-BW based latency, putting the metadata directly into
     the peer's pre-wired credit store (no fabric routing).
+
+    ``dst_rx_base_pa`` is the receiver's ``my_rx_base_pa`` for the direction
+    whose slot was consumed. The original sender matches this against
+    ``qp.peer.rx_base_pa`` to find the correct direction (ADR-0025 D3) —
+    unambiguous even when multiple directions share the same peer (e.g.
+    2-rank bidirectional ring).
     """
 
     consumer_seq: int            # my_tail at recv side (new tail value)
-    src_sip: int                 # which peer is sending the credit
+    dst_rx_base_pa: int          # receiver-side my_rx_base_pa (ADR-0025 D3)
+    src_sip: int                 # which peer is sending the credit (diag)
     src_cube: int
     src_pe: int
     src_direction: str           # sender-side direction (peer maps to its own)

src/kernbench/components/builtin/pe_ipcq.py

@@ -370,11 +370,21 @@ class PeIpcqComponent(ComponentBase):
     # ── Metadata arrival from PE_DMA (D9) ──
 
     def _handle_meta_arrival(self, msg: IpcqMetaArrival) -> None:
+        """Match arrival to the correct direction by dst_addr range (ADR-0025 D2).
+
+        Each direction has a unique rx buffer address range
+        ([my_rx_base_pa, my_rx_base_pa + n_slots * slot_size)). The token's
+        dst_addr (set by the sender's IPCQ when computing the peer slot
+        address) falls within exactly one such range. Address-based matching
+        is unambiguous even when multiple directions share the same peer
+        (2-rank bidirectional ring).
+        """
         token = msg.token
-        sender_key = (token.src_sip, token.src_cube, token.src_pe)
+        dst_addr = token.dst_addr
         for d, qp in self._queue_pairs.items():
-            p = qp["peer"]
-            if (p.sip, p.cube, p.pe) == sender_key:
+            base = qp["my_rx_base_pa"]
+            size = qp["n_slots"] * qp["slot_size"]
+            if base <= dst_addr < base + size:
                 qp["peer_head_cache"] = max(qp["peer_head_cache"], token.sender_seq + 1)
                 # Track arrived token for strict-mode peek
                 self._arrived_tokens.setdefault(d, []).append(token)
@@ -391,19 +401,22 @@ class PeIpcqComponent(ComponentBase):
                     if not ev.triggered:
                         ev.succeed()
                 return
-        # Unknown sender — silently drop (could log)
+        # Unknown dst_addr — silently drop (could log)
 
     # ── Credit return (fast path) ──
 
     def _credit_worker(self, env: simpy.Environment) -> Generator:
-        """Process IpcqCreditMetadata from credit_inbox."""
+        """Process IpcqCreditMetadata from credit_inbox.
+
+        Matches credit to the correct direction by `credit.dst_rx_base_pa ==
+        qp.peer.rx_base_pa` (ADR-0025 D3). This is unambiguous even when
+        multiple directions share the same peer (2-rank bidirectional ring).
+        """
         assert self._credit_inbox is not None
         while True:
             credit: IpcqCreditMetadata = yield self._credit_inbox.get()
-            sender_key = (credit.src_sip, credit.src_cube, credit.src_pe)
             for d, qp in self._queue_pairs.items():
-                p = qp["peer"]
-                if (p.sip, p.cube, p.pe) == sender_key:
+                if qp["peer"].rx_base_pa == credit.dst_rx_base_pa:
                     qp["peer_tail_cache"] = max(qp["peer_tail_cache"], credit.consumer_seq)
                     # Wake any blocked send on this direction
                     waiters = self._send_waiters.get(d, [])
@@ -421,12 +434,19 @@ class PeIpcqComponent(ComponentBase):
         new_tail: int,
     ) -> Generator:
         """Wait bottleneck-BW latency, then put IpcqCreditMetadata into peer
-        credit store (D9 fast path)."""
+        credit store (D9 fast path).
+
+        Carries ``dst_rx_base_pa`` = this PE's my_rx_base_pa for the
+        consumed direction. The peer (original sender) matches this against
+        qp.peer.rx_base_pa to identify the correct qp (ADR-0025 D3).
+        """
         latency_ns = self._credit_latency_ns(direction)
         if latency_ns > 0:
             yield env.timeout(latency_ns)
+        qp = self._queue_pairs[direction]
         meta = IpcqCreditMetadata(
             consumer_seq=new_tail,
+            dst_rx_base_pa=qp["my_rx_base_pa"],
             src_sip=self._self_sip,
             src_cube=self._self_cube,
             src_pe=self._self_pe,