rosotacom-dev 2.5.dev47__tar.gz → 2.5.dev48__tar.gz

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev47
+Version: 2.5.dev48
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/docs/forensics-report.md

@@ -93,6 +93,13 @@ delivered below it; `unknown` without sender-side records. `min_offered_hz` /
 rate — they never enter the delivered view, where the cross-peer join would
 upgrade receiver-inferred lost rows to delivered.
 
+The sending peer's status overview emits those rows itself for every wrapped
+stream (stage `com_out`, status `sent`, sequence gaps in its own observation as
+`unobserved` — see RFC 0003): record on both machines and place both peers'
+`logs/<peer>/status/` under one instance directory before running the report,
+and the `unknown` verdicts disappear. Recordings made before the sender-side
+rows existed stay `unknown` for their outbound streams.
+
 Events across streams and kinds are grouped into **incidents** when their
 windows touch (merge gap defaults to one bin): one degradation moment, several
 lenses on it.

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/docs/rfcs/0003-metric-backbone.md

@@ -56,6 +56,17 @@ Every metric on the wishlist is a projection of one recorded object per message:
   inter_arrival / jitter         — receiver-local regularity
 ```
 
+The **sending peer** records its own view of the same message at `com_out`
+(`direction: outbound`): `t_wrap` plus `t_com_out` (both its own clock, so
+`sections.wrap_to_com_out_ms` is the relay hop, and there is no θ). Its status
+values are deliberately different — `sent` for an observed message,
+`unobserved` for a gap in its own observation (the local best-effort observer
+missed it; the link cannot lose a message before the link) — so the offline
+join, which ranks only `lost < reordered < delivered`, can enrich a receiver
+row with sender timestamps but a sender row can never overwrite a receiver's
+`lost` verdict. This is what lets the forensics report classify a rate collapse
+as `source` vs `link`: offered (sender `t_wrap` bins) against delivered.
+
 **Why `epoch` is part of the key.** `universal_ota_wrapper` counts per topic
 from zero, so a peer that restarts inside an instance replays sequence numbers
 the receiver has already seen. The receiver detects the restart from the

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/src/rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py

@@ -253,6 +253,22 @@ class StageObserver(Node):
                     ),
                     None,
                 )
+                com_out = next(
+                    (
+                        context
+                        for context in contexts
+                        if context.get("stage") == "com_out"
+                        and context.get("direction") == "outbound"
+                    ),
+                    None,
+                )
+                keyframe: Optional[bool] = None
+                if com_in is not None or com_out is not None:
+                    try:
+                        if msg.msg_type == FFMPEG_PACKET_TYPE:
+                            keyframe = parse_keyframe_flag(bytes(msg.serialized_msg))
+                    except Exception:
+                        keyframe = None
                 if com_in is not None:
                     seq = int(msg.seq)
                     t_wrap_s = _stamp_seconds(msg.header.stamp)
@@ -262,12 +278,6 @@ class StageObserver(Node):
                         clock_offset_s = estimate["offset_s"]
                         rtt_s = estimate["rtt_s"]
                         delay_s = now_ros_s + clock_offset_s - t_wrap_s
-                    keyframe: Optional[bool] = None
-                    try:
-                        if msg.msg_type == FFMPEG_PACKET_TYPE:
-                            keyframe = parse_keyframe_flag(bytes(msg.serialized_msg))
-                    except Exception:
-                        keyframe = None
                     transit = {
                         "peer": com_in.get("peer"),
                         "source": com_in.get("source"),
@@ -279,6 +289,26 @@ class StageObserver(Node):
                         "t_com_in": now_ros_s,
                         "keyframe": keyframe,
                     }
+                elif com_out is not None:
+                    # The sending peer's own view of the same message: what the
+                    # source handed to the link, before any OTA hop. The wrapper
+                    # stamped `t_wrap` on THIS machine, so no peer offset applies
+                    # (same rule as the generic local-stage branch below) and the
+                    # delay is the wrap->com_out relay hop, not an OTA number.
+                    seq = int(msg.seq)
+                    t_wrap_s = _stamp_seconds(msg.header.stamp)
+                    delay_s = now_ros_s - t_wrap_s
+                    transit = {
+                        "peer": com_out.get("peer"),
+                        "source": com_out.get("source"),
+                        "target": com_out.get("target"),
+                        "topic": com_out.get("base"),
+                        "direction": com_out.get("direction"),
+                        "stage": com_out.get("stage"),
+                        "t_wrap": t_wrap_s,
+                        "t_com_out": now_ros_s,
+                        "keyframe": keyframe,
+                    }
             else:
                 header = getattr(msg, "header", None)
                 stamp = getattr(header, "stamp", None) if header is not None else None

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/src/rosotacom/resources/ws/ros2src/com_py/com_py/status_overview_core.py

@@ -451,6 +451,15 @@ class StageObservation:
                 self.sequence_events.append((now, expected_delta, missing, reordered, missing))
 
             if transit is not None and seq is not None:
+                # A sender-side com_out row observes its own machine's wrapper:
+                # a sequence gap there means the local observer missed the
+                # message, not that the link lost it, and an observed message
+                # was *sent*, not delivered. The distinct status values also
+                # keep the offline join honest: `join_transit_records` ranks
+                # only lost < reordered < delivered, so a sender row can never
+                # overwrite the receiving side's `lost` verdict for the same
+                # (source, topic, epoch, seq).
+                outbound = transit.get("direction") == "outbound"
                 common = {
                     "kind": "transit",
                     "peer": transit.get("peer"),
@@ -465,16 +474,21 @@ class StageObservation:
                     "epoch": self.epoch,
                 }
                 if missing_start is not None:
+                    gap_time_field = "t_com_out" if outbound else "t_com_in"
                     for missing_seq in range(missing_start, int(seq)):
                         self.transit_records.append(
                             {
                                 **common,
                                 "seq": missing_seq,
-                                "status": "lost",
+                                "status": "unobserved" if outbound else "lost",
                                 "t_wrap": None,
-                                "t_com_in": None,
+                                gap_time_field: None,
                                 "clock_offset_ms": None,
-                                "sections": {"ota_hop_ms": None},
+                                "sections": (
+                                    {"wrap_to_com_out_ms": None}
+                                    if outbound
+                                    else {"ota_hop_ms": None}
+                                ),
                                 "size_bytes": None,
                                 "inter_arrival_ms": None,
                                 "jitter_ms": None,
@@ -493,27 +507,42 @@ class StageObservation:
                 if inter_arrival_s is not None:
                     self.last_inter_arrival_s = inter_arrival_s
                 self.last_transit_recv_wall = wall
+                if outbound:
+                    # Same clock on both ends of this hop, so there is no
+                    # corrected/uncorrected pair and no OTA section: the only
+                    # honest number is the wrap->com_out relay hop.
+                    status = "sent"
+                    time_fields = {"t_com_out": transit.get("t_com_out")}
+                    sections: Dict[str, Any] = {
+                        "wrap_to_com_out_ms": (
+                            round(delay_s * 1000.0, 3) if delay_s is not None else None
+                        ),
+                    }
+                else:
+                    status = sequence_status
+                    time_fields = {"t_com_in": transit.get("t_com_in")}
+                    sections = {
+                        "ota_hop_ms": (
+                            round(delay_s * 1000.0, 3) if delay_s is not None else None
+                        ),
+                        "ota_hop_uncorrected_ms": (
+                            round(raw_delay_s * 1000.0, 3)
+                            if raw_delay_s is not None
+                            else None
+                        ),
+                    }
                 row = {
                     **common,
                     "seq": int(seq),
-                    "status": sequence_status,
+                    "status": status,
                     "t_wrap": transit.get("t_wrap"),
-                    "t_com_in": transit.get("t_com_in"),
+                    **time_fields,
                     "clock_offset_ms": (
                         round(clock_offset_s * 1000.0, 3)
                         if clock_offset_s is not None
                         else None
                     ),
-                    "sections": {
-                        "ota_hop_ms": (
-                            round(delay_s * 1000.0, 3) if delay_s is not None else None
-                        ),
-                        "ota_hop_uncorrected_ms": (
-                            round(raw_delay_s * 1000.0, 3)
-                            if raw_delay_s is not None
-                            else None
-                        ),
-                    },
+                    "sections": sections,
                     "size_bytes": size,
                     "inter_arrival_ms": (
                         round(inter_arrival_s * 1000.0, 3)

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev47
+Version: 2.5.dev48
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 47,
-  "node": "g73fa1de72a3f04bd36058dcc88da7d62b6668edb",
+  "distance": 48,
+  "node": "gaf076fb2c22a73a786a9a323f7382e74f2804e68",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-18"

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/tests/unit/test_status_overview_observer.py

@@ -328,3 +328,78 @@ def test_ota_unparseable_ffmpeg_payload_omits_the_flag(node_module: ModuleType)
     records = node.observations[topic].drain_transit_records()
     assert [record["seq"] for record in records] == [0, 1]
     assert all("keyframe" not in record for record in records)
+
+
+# ---------------------------------------------------------------------------
+# the sender-side com_out branch: what the source handed to the link (#293)
+# ---------------------------------------------------------------------------
+
+
+def _ota_out_observer(node_module: ModuleType, topic: str):
+    node = object.__new__(node_module.StageObserver)
+    node.observations = {topic: core.StageObservation(type_str="com_msgs/msg/OtaStamped")}
+    node._stage_metadata = {
+        topic: [
+            {
+                "peer": "a",
+                "source": "a",
+                "target": "b",
+                "base": "/cam",
+                "direction": "outbound",
+                "stage": "com_out",
+            }
+        ]
+    }
+    # A live peer estimate exists; the branch must not apply it to a local hop.
+    node.clock_estimator = _Estimator(5.0)
+    node.get_clock = lambda: SimpleNamespace(now=lambda: SimpleNamespace(nanoseconds=int(_NOW_S * 1e9)))
+    node.get_logger = lambda: SimpleNamespace(error=lambda *a, **k: None, warning=lambda *a, **k: None)
+    return node
+
+
+def test_com_out_ota_payload_produces_a_sent_transit_record(node_module: ModuleType) -> None:
+    topic = "/com/out/a/cam/ffmpeg/ota_stamped"
+    node = _ota_out_observer(node_module, topic)
+    cb = node._make_cb(topic)
+
+    cb(_ota_stamped(0, msg_type=ffmpeg_flags.FFMPEG_PACKET_TYPE, serialized_msg=_ffmpeg_packet(1)))
+    cb(_ota_stamped(1, msg_type=ffmpeg_flags.FFMPEG_PACKET_TYPE, serialized_msg=_ffmpeg_packet(0)))
+
+    records = node.observations[topic].drain_transit_records()
+    assert [(r["seq"], r["status"], r["keyframe"]) for r in records] == [
+        (0, "sent", True),
+        (1, "sent", False),
+    ]
+    first = records[0]
+    assert first["stage"] == "com_out"
+    assert first["direction"] == "outbound"
+    assert first["t_wrap"] == pytest.approx(_NOW_S - 0.03, abs=1e-6)
+    assert first["t_com_out"] == pytest.approx(_NOW_S, abs=1e-6)
+    assert "t_com_in" not in first
+    # Wrapper and observer share one clock, so the peer offset must not leak in.
+    assert first["clock_offset_ms"] is None
+    assert first["sections"]["wrap_to_com_out_ms"] == pytest.approx(30.0, abs=0.5)
+    assert "ota_hop_ms" not in first["sections"]
+
+
+def test_com_out_sequence_gap_is_unobserved_not_lost(node_module: ModuleType) -> None:
+    """A gap at com_out means the local observer missed the message, not the link."""
+    topic = "/com/out/a/cam/ffmpeg/ota_stamped"
+    node = _ota_out_observer(node_module, topic)
+    cb = node._make_cb(topic)
+
+    cb(_ota_stamped(0, msg_type=ffmpeg_flags.FFMPEG_PACKET_TYPE, serialized_msg=_ffmpeg_packet(1)))
+    cb(_ota_stamped(3, msg_type=ffmpeg_flags.FFMPEG_PACKET_TYPE, serialized_msg=_ffmpeg_packet(0)))
+
+    records = node.observations[topic].drain_transit_records()
+    assert [(r["seq"], r["status"]) for r in records] == [
+        (0, "sent"),
+        (1, "unobserved"),
+        (2, "unobserved"),
+        (3, "sent"),
+    ]
+    gap = records[1]
+    assert gap["t_wrap"] is None
+    assert gap["t_com_out"] is None
+    assert "t_com_in" not in gap
+    assert gap["sections"] == {"wrap_to_com_out_ms": None}

{rosotacom_dev-2.5.dev47 → rosotacom_dev-2.5.dev48}/tests/unit/test_transit.py

@@ -222,3 +222,41 @@ def test_nominal_send_period_ignores_the_step_across_a_restart() -> None:
     records += [{**_record(seq, "delivered", 5.0, t_wrap=100.0 + seq * 0.1), "epoch": 1} for seq in range(10)]
 
     assert _nominal_send_period_ms(records) == 100.0
+
+
+def test_sender_rows_can_never_mask_a_receiver_loss() -> None:
+    """The sending peer's com_out rows join with the receiver's rows by
+    (source, topic, epoch, seq). `sent` ranks below every receiver verdict in
+    `join_transit_records`, so a message the link lost stays lost -- while the
+    joined record still gains the sender's timestamps."""
+    sent = {
+        **_record(1, "sent", t_wrap=100.0),
+        "stage": "com_out",
+        "direction": "outbound",
+        "t_com_out": 100.005,
+        "sections": {"wrap_to_com_out_ms": 5.0},
+    }
+    lost = {**_record(1, "lost"), "stage": "com_in", "direction": "inbound"}
+
+    for ordering in ([sent, lost], [lost, sent]):
+        (joined,) = join_transit_records(ordering)
+        assert joined["status"] == "lost"
+        assert joined["t_wrap"] == 100.0
+        assert joined["t_com_out"] == 100.005
+
+    delivered = {**_record(1, "delivered", 12.0, t_wrap=100.0), "stage": "com_in", "direction": "inbound"}
+    (joined,) = join_transit_records([sent, delivered])
+    assert joined["status"] == "delivered"
+    assert joined["sections"]["ota_hop_ms"] == 12.0
+    assert joined["sections"]["wrap_to_com_out_ms"] == 5.0
+
+
+def test_unobserved_sender_gaps_do_not_count_as_loss() -> None:
+    records = [
+        {**_record(0, "sent", t_wrap=10.0), "direction": "outbound", "stage": "com_out"},
+        {**_record(1, "unobserved"), "direction": "outbound", "stage": "com_out"},
+        {**_record(2, "sent", t_wrap=10.2), "direction": "outbound", "stage": "com_out"},
+    ]
+    summary = summarize_transit_records(records)["topics"]["/x"]
+    assert summary["lost"] == 0
+    assert summary["loss_pct"] == 0.0