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>

tests/test_pe_ipcq.py

@@ -291,9 +291,12 @@ def test_send_blocks_when_peer_slot_full():
     env.run(until=20)
     assert not req5.done.triggered
 
-    # Send a credit return: peer (E direction, pe=1) consumed slot 0
+    # Send a credit return: peer (E direction, pe=1) consumed slot 0.
+    # dst_rx_base_pa is the peer-side rx buffer — which equals my qp_E's
+    # peer.rx_base_pa (0x10_000 from _install_two_neighbors).
     credit = IpcqCreditMetadata(
         consumer_seq=1,  # peer consumed up to my_tail=1
+        dst_rx_base_pa=0x10_000,  # E's peer.rx_base_pa (ADR-0025 D3)
         src_sip=0, src_cube=0, src_pe=1, src_direction="W",  # peer's view
     )
     comp.credit_inbox.put(credit)
@@ -315,3 +318,156 @@ def test_init_installs_neighbors():
     assert comp._queue_pairs["W"]["peer"].pe == 2
     assert comp._queue_pairs["E"]["my_head"] == 0
     assert comp._queue_pairs["E"]["peer_tail_cache"] == 0
+
+
+# ── ADR-0025: address-based matching in meta arrival / credit ────────
+
+
+def _install_same_peer_neighbors(
+    env: simpy.Environment, comp: PeIpcqComponent,
+) -> tuple[simpy.Store, simpy.Store]:
+    """Install E and W neighbors BOTH pointing to the same peer (pe=1).
+
+    This mirrors the 2-rank bidirectional ring topology (ADR-0025 motivation):
+    rank 0's E and W neighbors are the same peer rank, but target different
+    rx slots on that peer (E→peer's W-rx, W→peer's E-rx).
+
+    - E's peer.rx_base_pa = 0x10_000 (peer's W-rx buffer)
+    - W's peer.rx_base_pa = 0x20_000 (peer's E-rx buffer)
+    - my_rx_base_pa: E=0x30_000, W=0x40_000 (local rx for each dir)
+    """
+    peer_e_credit = simpy.Store(env)
+    peer_w_credit = simpy.Store(env)
+
+    ep_e = IpcqEndpoint(
+        sip=0, cube=0, pe=1,
+        buffer_kind="tcm",
+        rx_base_pa=0x10_000, rx_base_va=0,
+        n_slots=4, slot_size=4096,
+    )
+    ep_w = IpcqEndpoint(
+        sip=0, cube=0, pe=1,  # SAME peer as ep_e
+        buffer_kind="tcm",
+        rx_base_pa=0x20_000, rx_base_va=0,  # different target slot
+        n_slots=4, slot_size=4096,
+    )
+    init_msg = IpcqInitMsg(
+        correlation_id="t", request_id="t",
+        target_sips=(0,), target_cubes=(0,), target_pe=0,
+        entries=(
+            IpcqInitEntry(
+                direction="E", peer=ep_e,
+                my_rx_base_pa=0x30_000, my_rx_base_va=0,
+                n_slots=4, slot_size=4096,
+                peer_credit_store=peer_e_credit,
+            ),
+            IpcqInitEntry(
+                direction="W", peer=ep_w,
+                my_rx_base_pa=0x40_000, my_rx_base_va=0,
+                n_slots=4, slot_size=4096,
+                peer_credit_store=peer_w_credit,
+            ),
+        ),
+        backpressure_mode="sleep",
+        buffer_kind="tcm",
+        credit_size_bytes=16,
+    )
+    done = env.event()
+    comp.in_ports["host"].put(_FakeTxn(request=init_msg, done=done))
+    env.run(until=done)
+    return peer_e_credit, peer_w_credit
+
+
+def test_meta_arrival_matches_by_dst_addr_same_peer():
+    """ADR-0025 D2: when E and W point to the same peer (2-rank ring),
+    dst_addr range must determine which qp's peer_head_cache updates.
+
+    Under the old sender-key matching, the first matching direction (E)
+    would win for any arrival, regardless of which rx slot was written.
+    Under D2 address-based matching, dst_addr within W's rx range
+    (my_rx_base_pa_W .. +n_slots*slot_size) must update W, and dst_addr
+    within E's rx range must update E.
+    """
+    env = simpy.Environment()
+    comp = _make_pe_ipcq(env)
+    _install_same_peer_neighbors(env, comp)
+
+    # Arrival into W's rx buffer (my_rx_base_pa=0x40_000)
+    token_into_w = IpcqDmaToken(
+        src_addr=0, src_space="tcm",
+        dst_addr=0x40_000, dst_endpoint=comp._queue_pairs["W"]["peer"],
+        nbytes=64, handle_id="w1",
+        shape=(8,), dtype="f16",
+        sender_seq=0,
+        src_sip=0, src_cube=0, src_pe=1, src_direction="E",
+    )
+    comp.in_ports["host"].put(IpcqMetaArrival(token=token_into_w))
+    env.run(until=5)
+
+    # W's peer_head_cache should increment; E's stays 0.
+    assert comp._queue_pairs["W"]["peer_head_cache"] == 1, (
+        "W qp should have been updated because dst_addr is in W's rx range"
+    )
+    assert comp._queue_pairs["E"]["peer_head_cache"] == 0, (
+        "E qp should NOT be updated; current sender-key matching wrongly "
+        "picks the first direction with a matching peer"
+    )
+
+    # Second arrival into E's rx buffer (my_rx_base_pa=0x30_000)
+    token_into_e = IpcqDmaToken(
+        src_addr=0, src_space="tcm",
+        dst_addr=0x30_000, dst_endpoint=comp._queue_pairs["E"]["peer"],
+        nbytes=64, handle_id="e1",
+        shape=(8,), dtype="f16",
+        sender_seq=0,
+        src_sip=0, src_cube=0, src_pe=1, src_direction="W",
+    )
+    comp.in_ports["host"].put(IpcqMetaArrival(token=token_into_e))
+    env.run(until=10)
+
+    assert comp._queue_pairs["E"]["peer_head_cache"] == 1
+    assert comp._queue_pairs["W"]["peer_head_cache"] == 1
+
+
+def test_credit_matches_by_dst_rx_base_pa_same_peer():
+    """ADR-0025 D3: credit must carry dst_rx_base_pa (the receiver-side
+    rx buffer base) so the original sender can match it against
+    qp.peer.rx_base_pa and find the correct direction. Under old
+    sender-key matching, first-match-wins would always pick E when
+    E and W share the same peer.
+    """
+    env = simpy.Environment()
+    comp = _make_pe_ipcq(env)
+    _install_same_peer_neighbors(env, comp)
+
+    # Credit corresponding to a send through W direction:
+    # - My W sent to peer's rx at 0x20_000 (qp_w["peer"].rx_base_pa)
+    # - Peer consumed it; sends credit back with dst_rx_base_pa=0x20_000
+    # - Receiver (me, the original sender) should update W's peer_tail_cache
+    credit_for_w = IpcqCreditMetadata(
+        consumer_seq=1,
+        dst_rx_base_pa=0x20_000,  # matches W's peer.rx_base_pa
+        src_sip=0, src_cube=0, src_pe=1, src_direction="E",
+    )
+    comp.credit_inbox.put(credit_for_w)
+    env.run(until=5)
+
+    assert comp._queue_pairs["W"]["peer_tail_cache"] == 1, (
+        "W's peer_tail_cache should update — credit.dst_rx_base_pa matches "
+        "W qp's peer.rx_base_pa"
+    )
+    assert comp._queue_pairs["E"]["peer_tail_cache"] == 0, (
+        "E's peer_tail_cache should NOT update"
+    )
+
+    # Second credit: for E direction
+    credit_for_e = IpcqCreditMetadata(
+        consumer_seq=2,
+        dst_rx_base_pa=0x10_000,  # matches E's peer.rx_base_pa
+        src_sip=0, src_cube=0, src_pe=1, src_direction="W",
+    )
+    comp.credit_inbox.put(credit_for_e)
+    env.run(until=10)
+
+    assert comp._queue_pairs["E"]["peer_tail_cache"] == 2
+    assert comp._queue_pairs["W"]["peer_tail_cache"] == 1