commit - release 1

src/kernbench/sim_engine/transaction.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import simpy
+
+
+@dataclass
+class Transaction:
+    """In-flight request traversing the device fabric hop-by-hop (ADR-0015 D4).
+
+    A Transaction carries a host request through one leg of the device fabric.
+    Each component on the path reads from its in_port, processes (overhead_ns or
+    other latency), and advances the Transaction to the next hop via out_port.
+    Wire processes (ADR-0015 D2) model propagation delay between hops.
+
+    Multi-leg flows (e.g. IO_CPU → M_CPU as leg 1, M_CPU.DMA → HBM as leg 2)
+    use separate Transactions: the terminal component of leg 1 creates leg 2
+    and waits for leg 2's done before succeeding leg 1's done.
+    """
+
+    request: Any            # original host request (MemoryReadMsg, KernelLaunchMsg, …)
+    path: list[str]         # node_id sequence for this leg
+    step: int               # index of the component currently holding this Transaction
+    nbytes: int             # payload size (bytes)
+    done: simpy.Event       # succeeded when this leg completes
+    drain_ns: float = 0.0   # wormhole drain time: nbytes / bottleneck_bw (applied once at terminal)
+    is_response: bool = False  # True when carrying ResponseMsg on reverse path
+    result_data: dict[str, Any] = field(default_factory=dict)  # PE-level metrics (pe_exec_ns, etc.)
+
+    @property
+    def next_hop(self) -> str | None:
+        """Node id of the next component, or None if this is the terminal hop."""
+        nxt = self.step + 1
+        return self.path[nxt] if nxt < len(self.path) else None
+
+    def advance(self) -> Transaction:
+        """Return a copy of this Transaction advanced one step along the path."""
+        return Transaction(
+            request=self.request,
+            path=self.path,
+            step=self.step + 1,
+            nbytes=self.nbytes,
+            done=self.done,
+            drain_ns=self.drain_ns,
+            is_response=self.is_response,
+            result_data=self.result_data,
+        )