rosotacom-dev 2.5.dev56__tar.gz → 2.5.dev58__tar.gz

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/PKG-INFO

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

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/session-configuration.md

@@ -720,8 +720,35 @@ ros2 run com_py playout_pacer --ros-args \
   -p target_ms:=350.0 -p adaptive:=true
 ```
 
-It republishes on `<topic>/paced` plus `.../paced/budget_ms` and
-`.../paced/queue_depth` debug topics.
+It republishes on `<topic>/paced` plus three topics next to it:
+`.../paced/budget_ms` and `.../paced/queue_depth` at 1 Hz, and
+`.../paced/hold_ms` with every release, carrying how long *that* message was
+actually held.
+
+##### What the status overview does with it
+
+A paced stage's age is the link plus a delay this session asked for, and one
+number cannot be judged against a threshold meant for the link. So the
+generator names the pacer's report on the stage it explains
+(`paced_hold_topic` in `pipeline_spec.yaml`), and `status_overview` takes the
+hold back out before classifying:
+
+```
+native_in  FLOWING  .../ffmpeg/compressed  10.0Hz 286ms(link 46+paced 240) ...
+```
+
+`latency_ms` stays the age on screen; `link_latency_ms` and `pacing_hold_ms`
+are the split, and the quality verdict uses the former. Without this the
+default 200 ms bad-threshold — set before anything on a link was held on
+purpose — marks every healthy paced stream BAD, which is how an operator learns
+to stop reading the panel.
+
+It is the *applied* hold that is subtracted, never the configured budget: a
+message that arrived later than its release time passes straight through, is
+reported as held for 0 ms, and still flags. A budget-based correction would
+credit that message a buffer it never received and quietly stop reporting a slow
+link. Before the pacer has reported at all, nothing is subtracted — neither zero
+nor the budget is a safe guess.
 
 `type: foxglove` supports (CompressedVideo):
 - `gop_size` (int)

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/src/rosotacom/resources/ws/ros2src/com_py/com_py/playout_pacer.py

@@ -8,7 +8,16 @@ Inserted between the OTA unwrapper and a decoder chain it turns network jitter
 into a constant, bounded age instead of visible stutter.
 
 Debug topics next to the output: ``.../paced/budget_ms`` (current delay
-budget) and ``.../paced/queue_depth``.
+budget) and ``.../paced/queue_depth``, both at 1 Hz, and ``.../paced/hold_ms``
+— published with *every* release, carrying how long that message was actually
+held.
+
+``hold_ms`` exists so the status overview can tell the link's contribution from
+this node's. Deliberately the applied hold rather than the budget: a message
+that arrived later than its release time passes straight through and is held
+for 0 ms, so a genuinely slow link cannot be credited with a buffer it never
+used. Subtracting the *budget* would do exactly that, and would quietly stop
+reporting the problem it exists to make visible.
 """
 
 from __future__ import annotations
@@ -62,6 +71,7 @@ class PlayoutPacerNode(Node):
         self._pub = self.create_publisher(msg_cls, out_topic, qos)
         self._budget_pub = self.create_publisher(Float64, out_topic + "/budget_ms", 10)
         self._depth_pub = self.create_publisher(Int32, out_topic + "/queue_depth", 10)
+        self._hold_pub = self.create_publisher(Float64, out_topic + "/hold_ms", 10)
         self.create_subscription(msg_cls, topic, self._on_message, qos)
         # 2 ms release tick: bounds added jitter to well below frame cadence.
         self.create_timer(0.002, self._release_due)
@@ -72,12 +82,16 @@ class PlayoutPacerNode(Node):
         now = time.time()
         stamp = msg.header.stamp.sec + msg.header.stamp.nanosec * 1e-9
         release = self.schedule.on_message(stamp, now)
-        self._queue.append((release, msg))
+        self._queue.append((release, msg, now))
 
     def _release_due(self) -> None:
         now = time.time()
         while self._queue and self._queue[0][0] <= now:
-            self._pub.publish(self._queue.popleft()[1])
+            release, msg, arrival = self._queue.popleft()
+            self._pub.publish(msg)
+            # What this node added, not what it was allowed to add. Clamped
+            # because a late message's release time is already in the past.
+            self._hold_pub.publish(Float64(data=max(0.0, (release - arrival) * 1000.0)))
 
     def _publish_debug(self) -> None:
         self._budget_pub.publish(Float64(data=float(self.schedule.budget_ms)))

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/src/rosotacom/resources/ws/ros2src/com_py/com_py/playout_pacer_core.py

@@ -32,7 +32,10 @@ class PacerConfig:
     adaptive: bool = True
     percentile: float = 0.95  # of (arrival - stamp), window-local
     margin_ms: float = 40.0  # headroom above the tracked percentile
-    window: int = 400  # samples (~40 s at 10 Hz)
+    #: Samples (~40 s at 10 Hz). Bounds both the tracked percentile and the
+    #: delay floor, so how fast the schedule re-anchors after the path changes
+    #: is this number: a longer window is steadier and slower to recover.
+    window: int = 400
 
     def __post_init__(self) -> None:
         if not 0.0 < self.percentile < 1.0:
@@ -72,8 +75,18 @@ class PlayoutSchedule:
         """
         d = arrival_s - stamp_s
         self._d.append(d)
-        if self._d_floor is None or d < self._d_floor:
-            self._d_floor = d
+        # The minimum over the *window*, not over all time. An all-time floor
+        # can only fall, so any upward shift in `arrival - stamp` -- a clock
+        # step, an NTP correction, a route change, a looping replay -- leaves
+        # every later message past `stamp + floor + budget`, and the pacer
+        # degrades to a pass-through it can never come back from. Found on the
+        # fleet e2e, where a bag loop moved the delay by the bag's length and
+        # the centre's camera ran unpaced for the rest of the run with every
+        # panel healthy. Windowed, the same shift re-anchors within one window.
+        #
+        # O(window) per message: 400 floats at 10 Hz. A monotonic deque would
+        # make it O(1) and is not worth the machinery at these rates.
+        self._d_floor = min(self._d)
         release = stamp_s + self._d_floor + self.budget_ms / 1000.0
         if release < arrival_s:  # already late: pass through immediately
             release = arrival_s

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

@@ -71,6 +71,7 @@ from com_py.ffmpeg_flags import FFMPEG_PACKET_TYPE, parse_keyframe_flag
 from com_py.link_bytes import LinkByteSampler, resolve_link_interface
 from com_py.link_trace import LinkTraceRecorder
 from com_py.status_overview_core import (
+    SCALAR_MSG_TYPE,
     STARTUP_GRACE_S,
     ClockOffsetEstimator,
     StageObservation,
@@ -309,6 +310,11 @@ class StageObserver(Node):
                         "t_com_out": now_ros_s,
                         "keyframe": keyframe,
                     }
+            elif obs.type_str == SCALAR_MSG_TYPE:
+                # Not a stage: a number this node reads to interpret one. The
+                # pacing hold arrives here (`.../paced/hold_ms`); it carries no
+                # header, so there is no latency to record, only the value.
+                obs.last_value = float(msg.data)
             else:
                 header = getattr(msg, "header", None)
                 stamp = getattr(header, "stamp", None) if header is not None else None

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

@@ -61,6 +61,12 @@ GOOD = "GOOD"
 DEGRADED = "DEGRADED"
 BAD = "BAD"
 
+#: A stage whose age includes a delay this session asked for names the topic on
+#: which the node responsible reports what it actually held. Set by the
+#: generator for a decode that reads a playout pacer's output.
+PACED_HOLD_KEY = "paced_hold_topic"
+SCALAR_MSG_TYPE = "std_msgs/msg/Float64"
+
 # Topic-level rollup
 OK = "OK"
 PARTIAL = "PARTIAL"
@@ -371,6 +377,9 @@ class StageObservation:
     last_recv_wall: Optional[float] = None
     last_delay_s: Optional[float] = None
     last_raw_delay_s: Optional[float] = None
+    #: Payload of the last message, for the scalar topics this node reads as
+    #: numbers rather than observes as stages (the pacing hold).
+    last_value: Optional[float] = None
     last_rtt_s: Optional[float] = None
     last_clock_offset_s: Optional[float] = None
     # (t_mono, size_bytes, delay_s_or_None)
@@ -673,6 +682,21 @@ class StatusAggregator:
         self._startup_pending: Optional[Tuple[float, set]] = None
 
     # -- observation lookup --
+    def _pacing_hold_ms(self, stage: Dict[str, Any]) -> Optional[float]:
+        """How long this session deliberately held the last message of a stage.
+
+        None whenever the answer is not actually known -- no pacer named, or the
+        pacer has not reported yet. Guessing zero would read a paced picture as
+        a slow link; guessing the configured budget would do the opposite and
+        credit a hold that a late message never received.
+        """
+        hold_topic = stage.get(PACED_HOLD_KEY)
+        if not hold_topic:
+            return None
+        observer = self._observers.get("local")
+        observation = observer.observations.get(str(hold_topic)) if observer else None
+        return None if observation is None else observation.last_value
+
     def _obs_for(self, stage: Dict[str, Any]) -> Optional[StageObservation]:
         domain = stage.get("domain", "local")
         observer = self._observers.get(domain) or self._observers.get("local")
@@ -714,6 +738,9 @@ class StatusAggregator:
             "observation": "graph" if obs is not None and obs.graph_only else "payload",
             "inferred_from": None,
             "latched": str((expect or {}).get("mode", "")).strip().lower() == "latched",
+            # Split of `latency_ms` for a stage this session delays on purpose.
+            "pacing_hold_ms": None,
+            "link_latency_ms": None,
         }
         if obs is None:
             return result
@@ -727,6 +754,10 @@ class StatusAggregator:
         result["age_s"] = round(m["age_s"], 3) if m["age_s"] is not None else None
         if m["last_delay_s"] is not None:
             result["latency_ms"] = round(m["last_delay_s"] * 1000.0, 1)
+            hold_ms = self._pacing_hold_ms(stage)
+            if hold_ms is not None:
+                result["pacing_hold_ms"] = round(hold_ms, 1)
+                result["link_latency_ms"] = round(max(0.0, result["latency_ms"] - hold_ms), 1)
         if m["last_raw_delay_s"] is not None:
             result["latency_uncorrected_ms"] = round(m["last_raw_delay_s"] * 1000.0, 1)
         if m["last_rtt_s"] is not None:
@@ -759,7 +790,9 @@ class StatusAggregator:
             return result
 
         result["state"] = FLOWING
-        quality, reason = self._classify_quality(m, expected_hz, expect)
+        quality, reason = self._classify_quality(
+            m, expected_hz, expect, pacing_hold_ms=result["pacing_hold_ms"]
+        )
         result["quality"] = quality
         result["quality_reason"] = reason
         return result
@@ -823,7 +856,12 @@ class StatusAggregator:
                 self._copy_inferred_activity(stage_result, source)
 
     def _classify_quality(
-        self, m: Dict[str, Any], expected_hz: Optional[float], expect: Optional[Dict[str, Any]] = None
+        self,
+        m: Dict[str, Any],
+        expected_hz: Optional[float],
+        expect: Optional[Dict[str, Any]] = None,
+        *,
+        pacing_hold_ms: Optional[float] = None,
     ) -> Tuple[str, Optional[str]]:
         expect = expect or {}
         hz_exp = expect.get("hz") or {}
@@ -833,8 +871,17 @@ class StatusAggregator:
         # Latency: a declared `expect.latency_ms.max` overrides the global bad
         # threshold; the good band stays the default so a tight contract still
         # surfaces a DEGRADED before BAD where it makes sense.
+        #
+        # A stage the session delays on purpose is judged on what is left after
+        # that delay is taken back out. Otherwise a threshold calibrated for a
+        # link measures a buffer, which reads as a fault on a healthy stream and
+        # teaches an operator to stop believing the panel. The subtracted value
+        # is the hold actually applied, so a late message -- which the pacer
+        # passes straight through -- is credited nothing and still flags.
         bad_lat = float(lat_exp["max"]) if "max" in lat_exp else self._delay_bad_ms
         delay_ms = (m["last_delay_s"] * 1000.0) if m["last_delay_s"] is not None else None
+        if delay_ms is not None and pacing_hold_ms is not None:
+            delay_ms = max(0.0, delay_ms - pacing_hold_ms)
         if delay_ms is not None:
             if delay_ms >= bad_lat:
                 return BAD, "latency"
@@ -1142,7 +1189,16 @@ class StatusAggregator:
                 if st["state"] in (FLOWING, STALE):
                     parts = [f"{st['hz']:.1f}Hz"]
                     if st["latency_ms"] is not None:
-                        parts.append(f"{st['latency_ms']:.0f}ms")
+                        # A paced stage reads as one big number unless the split
+                        # is on the same line: what the link cost, and what this
+                        # session chose to add on top of it.
+                        if st.get("pacing_hold_ms") is not None:
+                            parts.append(
+                                f"{st['latency_ms']:.0f}ms"
+                                f"(link {st['link_latency_ms']:.0f}+paced {st['pacing_hold_ms']:.0f})"
+                            )
+                        else:
+                            parts.append(f"{st['latency_ms']:.0f}ms")
                     elif st["latency_uncorrected_ms"] is not None:
                         parts.append(f"{st['latency_uncorrected_ms']:.0f}ms(raw)")
                     if st["loss_pct"] is not None:
@@ -1298,7 +1354,12 @@ class StatusAggregator:
 
 
 def collect_stage_topics(spec: Dict[str, Any]) -> Dict[str, Dict[str, Optional[str]]]:
-    """Return {domain: {topic: type_hint}} from the pipeline spec."""
+    """Return {domain: {topic: type_hint}} from the pipeline spec.
+
+    Includes the pacing-hold topics a stage names: they are not stages of the
+    link -- nothing is delivered on them -- but the aggregator has to read them
+    to tell this session's deliberate delay from the network's.
+    """
     by_domain: Dict[str, Dict[str, Optional[str]]] = {"local": {}, "ota": {}}
     for topic_spec in spec.get("topics", []):
         type_hint = topic_spec.get("type")
@@ -1307,6 +1368,9 @@ def collect_stage_topics(spec: Dict[str, Any]) -> Dict[str, Dict[str, Optional[s
             by_domain.setdefault(domain, {})
             existing = by_domain[domain].get(stage["topic"])
             by_domain[domain][stage["topic"]] = existing or stage.get("type") or type_hint
+            hold_topic = stage.get(PACED_HOLD_KEY)
+            if hold_topic:
+                by_domain["local"].setdefault(str(hold_topic), SCALAR_MSG_TYPE)
     return by_domain
 
 

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/src/rosotacom/resources/ws/session/creation/generate_session_files.py

@@ -1666,17 +1666,23 @@ def _build_status_pipeline_spec(
             if postprocessed != final:
                 native_in_type = base_type
                 transport = p.get("transport")
+                native_in: Dict[str, Any] = {
+                    "stage": "native_in",
+                    "topic": _relay_in_local_topic(postprocessed),
+                    "type": native_in_type,
+                    "domain": "local",
+                    "produced_by": "postprocessing",
+                }
                 if isinstance(transport, TransportSpec) and transport.remote_republish:
-                    native_in_type = REPUBLISH_OUTPUT_TYPES[transport.remote_republish]
-                stages.append(
-                    {
-                        "stage": "native_in",
-                        "topic": _relay_in_local_topic(postprocessed),
-                        "type": native_in_type,
-                        "domain": "local",
-                        "produced_by": "postprocessing",
-                    }
-                )
+                    native_in["type"] = REPUBLISH_OUTPUT_TYPES[transport.remote_republish]
+                    if transport.playout is not None and playout_republish(transport.playout) != "unpaced":
+                        # This stage's age is the link plus a hold this session
+                        # asked for. The pacer reports the hold it applied; naming
+                        # the topic here is what lets the status separate the two
+                        # instead of reading a deliberate buffer as a fault.
+                        paced = _relay_in_local_topic(str(p.get("irt_in"))) + "/paced"
+                        native_in["paced_hold_topic"] = f"{paced}/hold_ms"
+                stages.append(native_in)
 
             topics.append(
                 {

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/src/rosotacom/status_eval.py

@@ -265,10 +265,19 @@ def _check_expect(
             failures.append(f"[{peer}] {base}: latency_ms.stage '{stage_name}' not in pipeline")
             return failures
         lat_stage = named
-    lat = lat_stage.get("latency_ms")
+    # A stage the session delays on purpose reports the split, and `expect` is
+    # about what the *link* delivers -- the buffer is already bounded by the
+    # `playout` block that asked for it. The live status classifies on the same
+    # number, and the two must not disagree about one contract: that is how a
+    # session ends up passing `rosotacom test` while its own panel reads BAD.
+    lat = lat_stage.get("link_latency_ms")
+    measured = "link latency"
+    if lat is None:
+        lat = lat_stage.get("latency_ms")
+        measured = "latency"
     if "max" in lat_exp and (lat is None or lat > lat_exp["max"]):
         where = f" at '{stage_name}'" if stage_name else ""
-        failures.append(f"[{peer}] {base}: latency {lat}ms{where} > expected max {lat_exp['max']}ms")
+        failures.append(f"[{peer}] {base}: {measured} {lat}ms{where} > expected max {lat_exp['max']}ms")
 
     loss_exp = expect.get("loss_pct") or {}
     if "max" in loss_exp:

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/src/rosotacom_dev.egg-info/PKG-INFO

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

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 56,
-  "node": "g18a62c4bee965c3d64b7eaa70544f6bb7f078a98",
+  "distance": 58,
+  "node": "ge746c2a24a5de807925ed1cc3b61921a542c2ac2",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/tests/contract/test_generated_topics_have_a_producer.py

@@ -218,7 +218,7 @@ def touches(params: dict, peer_dir: Path) -> Touches:
     for index in _slots(params, "pace_{}_topic", limit=4):
         topic = _one(params, f"pace_{index}_topic")
         result.through(str(topic), f"{topic}/paced")
-        result.writes.update({f"{topic}/paced/budget_ms", f"{topic}/paced/queue_depth"})
+        result.writes.update({f"{topic}/paced/budget_ms", f"{topic}/paced/queue_depth", f"{topic}/paced/hold_ms"})
 
     # NOR: relays a prefixed, suffixed name back onto the bare base, so a local
     # consumer (a TF tree) finds the name it expects.
@@ -245,14 +245,35 @@ def touches(params: dict, peer_dir: Path) -> Touches:
 
     # Observability: reads only, never republishes.
     result.reads.update(_many(params, "metric_stage_topics"))
+    # STAT: the status overview reads the pacing hold a stage names, to tell
+    # this session's deliberate delay from the network's. It is configured out
+    # of the pipeline spec rather than out of these parameters, but it is a read
+    # by a node this peer starts, so it belongs here -- a hold topic no pacer
+    # publishes would leave the status silently subtracting nothing.
+    result.reads.update(paced_hold_topics(peer_dir))
 
     return result
 
 
+def _spec(peer_dir: Path) -> dict:
+    path = peer_dir / "pipeline_spec.yaml"
+    if not path.is_file():
+        return {}
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def _stages(peer_dir: Path) -> Iterator[dict]:
+    for topic in _spec(peer_dir).get("topics", []):
+        yield from topic.get("stages", [])
+
+
+def paced_hold_topics(peer_dir: Path) -> set[str]:
+    return {stage["paced_hold_topic"] for stage in _stages(peer_dir) if stage.get("paced_hold_topic")}
+
+
 def spec_topics(peer_dir: Path) -> set[str]:
     """Every topic this peer's pipeline spec models, at any stage."""
-    spec = yaml.safe_load((peer_dir / "pipeline_spec.yaml").read_text(encoding="utf-8"))
-    return {stage["topic"] for topic in spec.get("topics", []) for stage in topic.get("stages", [])}
+    return {stage["topic"] for stage in _stages(peer_dir)}
 
 
 # ---------------------------------------------------------------------------
@@ -352,7 +373,12 @@ def test_the_composed_names_are_the_ones_the_template_composes() -> None:
     # reads that name, and `touches` claims those two writes, so all three have
     # to agree -- they are three files apart and nothing else compares them.
     pacer = PACER_PY.read_text(encoding="utf-8")
-    for composed in ('declare_parameter("topic_suffix", "/paced")', '+ "/budget_ms"', '+ "/queue_depth"'):
+    for composed in (
+        'declare_parameter("topic_suffix", "/paced")',
+        '+ "/budget_ms"',
+        '+ "/queue_depth"',
+        '+ "/hold_ms"',
+    ):
         assert composed in pacer, f"the pacer no longer composes {composed}"
 
 

rosotacom_dev-2.5.dev58/tests/unit/test_playout_pacer.py

@@ -0,0 +1,167 @@
+"""Playout pacer core — schedule properties on synthetic arrival traces."""
+
+from __future__ import annotations
+
+import random
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+WS_PY = REPO_ROOT / "src" / "rosotacom" / "resources" / "ws" / "ros2src" / "com_py"
+sys.path.insert(0, str(WS_PY))
+
+from com_py.playout_pacer_core import PacerConfig, PlayoutSchedule  # noqa: E402
+
+
+def _run(schedule: PlayoutSchedule, stamps, delays):
+    releases = []
+    for stamp, d in zip(stamps, delays, strict=True):
+        releases.append(schedule.on_message(stamp, stamp + d))
+    return releases
+
+
+def test_jittered_arrivals_release_on_a_regular_grid() -> None:
+    # 10 Hz stream, delay jitter far above the frame period: released cadence
+    # must be the sender cadence, not the arrival cadence.
+    rng = random.Random(1)
+    stamps = [i / 10 for i in range(300)]
+    delays = [0.030 + rng.random() * 0.120 for _ in stamps]  # 30-150 ms
+    schedule = PlayoutSchedule(PacerConfig(adaptive=True, min_ms=100.0, max_ms=800.0))
+    releases = _run(schedule, stamps, delays)
+    gaps = [b - a for a, b in zip(releases[50:], releases[51:], strict=False)]
+    assert max(gaps) < 0.150  # no visible stutter (>150 ms) left
+    assert sum(1 for g in gaps if abs(g - 0.1) < 0.01) / len(gaps) > 0.95
+
+
+def test_late_message_passes_through_immediately_and_order_is_kept() -> None:
+    schedule = PlayoutSchedule(PacerConfig(adaptive=False, target_ms=200.0))
+    stamps = [i / 10 for i in range(50)]
+    delays = [0.030] * 50
+    delays[25] = 0.700  # one message far beyond any budget
+    releases = _run(schedule, stamps, delays)
+    # Late message is released at its arrival, not held further...
+    assert releases[25] == pytest.approx(stamps[25] + 0.700)
+    # ...and ordering is never violated.
+    assert all(b >= a for a, b in zip(releases, releases[1:], strict=False))
+
+
+def test_budget_is_clock_offset_proof() -> None:
+    # Same jitter, sender clock shifted by -3 s: the budget must not explode.
+    rng = random.Random(2)
+    delays = [0.030 + rng.random() * 0.060 for _ in range(200)]
+    plain = PlayoutSchedule()
+    shifted = PlayoutSchedule()
+    for i, d in enumerate(delays):
+        plain.on_message(i / 10, i / 10 + d)
+        shifted.on_message(i / 10 - 3.0, i / 10 + d)  # stamp 3 s in the "past"
+    assert shifted.budget_ms == pytest.approx(plain.budget_ms, rel=0.05)
+    assert shifted.budget_ms < 800.0
+
+
+def test_adaptive_budget_tracks_jitter_and_respects_clamps() -> None:
+    calm = PlayoutSchedule(PacerConfig(min_ms=100.0, max_ms=800.0, margin_ms=40.0))
+    rough = PlayoutSchedule(PacerConfig(min_ms=100.0, max_ms=800.0, margin_ms=40.0))
+    rng = random.Random(3)
+    for i in range(300):
+        calm.on_message(i / 10, i / 10 + 0.030 + rng.random() * 0.010)
+        rough.on_message(i / 10, i / 10 + 0.030 + rng.random() * 0.400)
+    assert calm.budget_ms == pytest.approx(100.0)  # clamped at min
+    assert rough.budget_ms > 300.0
+    assert rough.budget_ms <= 800.0
+
+
+def test_config_validation() -> None:
+    with pytest.raises(ValueError):
+        PacerConfig(percentile=1.5)
+    with pytest.raises(ValueError):
+        PacerConfig(min_ms=500.0, max_ms=100.0)
+    with pytest.raises(ValueError):
+        PacerConfig(window=3)
+
+
+# The hold the node reports (#301).
+#
+# `.../paced/hold_ms` carries what this node actually added, so the status
+# overview can take it back out of a decoded stage's age and judge what is left
+# -- the link. The node computes `max(0, release - arrival)`; both halves of
+# that clamp are properties of the schedule, so they are asserted here rather
+# than in three lines of publishing glue.
+
+
+def _hold_ms(schedule: PlayoutSchedule, stamp: float, arrival: float) -> float:
+    """What the node publishes for a message: the delay it applied, never negative."""
+    return max(0.0, (schedule.on_message(stamp, arrival) - arrival) * 1000.0)
+
+
+def test_the_reported_hold_is_what_was_added_not_what_was_allowed() -> None:
+    schedule = PlayoutSchedule(PacerConfig(adaptive=False, target_ms=200.0))
+    # First message sets the floor at its own delay, so it is released at
+    # floor + 200 ms and waits exactly the budget.
+    assert _hold_ms(schedule, 0.0, 0.030) == pytest.approx(200.0, abs=1.0)
+    # One that arrives 150 ms later than the floor has already spent 150 of the
+    # budget on the wire and waits only the remainder.
+    assert _hold_ms(schedule, 1.0, 1.180) == pytest.approx(50.0, abs=1.0)
+
+
+def test_a_late_message_is_reported_as_held_for_nothing() -> None:
+    """The clamp: a pass-through must not be credited with a buffer it skipped."""
+    schedule = PlayoutSchedule(PacerConfig(adaptive=False, target_ms=200.0))
+    _hold_ms(schedule, 0.0, 0.030)
+
+    assert _hold_ms(schedule, 1.0, 1.400) == 0.0
+
+
+# The floor has to be able to rise again (#312).
+#
+# Every budget is anchored to `d_floor`, the fastest path observed. Taking that
+# over all time rather than over the window means it can only fall, so one
+# upward shift in `arrival - stamp` puts every later message past its release
+# time and the pacer becomes a pass-through it never recovers from. A clock step
+# on either peer is enough; the fleet e2e's looping bag replay does it every
+# lap, and until #301 the symptom was invisible -- node up, topic flowing,
+# nothing re-timed.
+
+
+def _hold_p50(schedule: PlayoutSchedule, count: int, stamp0: float, offset: float) -> float:
+    holds = []
+    for index in range(count):
+        stamp = stamp0 + index * 0.1
+        # 10 ms most of the time, 50 ms every third message: enough jitter for
+        # an adaptive budget to have something to track.
+        arrival = stamp + offset + (0.05 if index % 3 == 0 else 0.01)
+        holds.append(max(0.0, (schedule.on_message(stamp, arrival) - arrival) * 1000.0))
+    return sorted(holds)[len(holds) // 2]
+
+
+def test_a_delay_step_up_is_re_anchored_within_one_window() -> None:
+    schedule = PlayoutSchedule(PacerConfig(adaptive=True, min_ms=100.0, max_ms=300.0))
+    window = schedule.config.window
+
+    assert _hold_p50(schedule, 500, 0.0, 0.20) == pytest.approx(100.0, abs=5.0)
+    # The step itself is absorbed, not smoothed: those messages are genuinely
+    # late relative to what was known, and pass through.
+    _hold_p50(schedule, window, 1000.0, 161.20)
+    # One window later the floor describes the new path again.
+    assert _hold_p50(schedule, 500, 2000.0, 161.20) == pytest.approx(100.0, abs=5.0)
+
+
+def test_a_constant_offset_is_still_absorbed_entirely() -> None:
+    """The property the floor exists for: no clock synchronization needed."""
+    near = PlayoutSchedule(PacerConfig(adaptive=True, min_ms=100.0, max_ms=300.0))
+    far = PlayoutSchedule(PacerConfig(adaptive=True, min_ms=100.0, max_ms=300.0))
+
+    assert _hold_p50(near, 500, 0.0, 0.20) == pytest.approx(_hold_p50(far, 500, 0.0, 3600.20), abs=1.0)
+
+
+def test_the_step_neither_drops_nor_reorders() -> None:
+    schedule = PlayoutSchedule(PacerConfig(adaptive=True, min_ms=100.0, max_ms=300.0))
+    releases = []
+    for index in range(600):
+        stamp = index * 0.1
+        offset = 0.20 if index < 300 else 161.20
+        releases.append(schedule.on_message(stamp, stamp + offset + 0.01))
+
+    assert len(releases) == 600
+    assert releases == sorted(releases)

{rosotacom_dev-2.5.dev56 → rosotacom_dev-2.5.dev58}/tests/unit/test_session_pipeline.py

@@ -394,3 +394,54 @@ def test_every_mode_delivers_the_same_topic_name(tmp_path: Path) -> None:
     delivered.add(generator._delivered_topic(unpaced_link, unpaced_link["final"]))
 
     assert len(delivered) == 1, delivered
+
+
+# The status has to be told which pacer belongs to which stage (#301).
+#
+# A decoded stage's age is the link plus a hold this session asked for, and the
+# status overview cannot tell them apart by looking at one number. The generator
+# knows both nodes, so it names the pacer's report on the stage it explains --
+# rather than the status guessing from a topic-name convention.
+
+
+def _native_in(receiver: str) -> dict:
+    spec = yaml.safe_load(receiver)
+    for topic in spec["topics"]:
+        if topic["direction"] == "inbound":
+            for stage in topic["stages"]:
+                if stage["stage"] == "native_in":
+                    return stage
+    raise AssertionError("no inbound native_in stage")
+
+
+def _receiver_spec(tmp_path: Path, playout: dict | None) -> str:
+    transport: dict = {"type": "ffmpeg", "remote_republish": "compressed"}
+    if playout is not None:
+        transport["playout"] = playout
+    generator.func(
+        session_config_obj=_camera_cfg({"transport": transport, "use_ota_wrapper": True}),
+        output_dir=str(tmp_path),
+        force=True,
+        peer_addresses={"a": "127.0.0.1", "b": "127.0.0.2"},
+    )
+    return (tmp_path / "a" / "pipeline_spec.yaml").read_text(encoding="utf-8")
+
+
+def test_a_paced_decode_names_the_pacer_that_explains_its_age(tmp_path: Path) -> None:
+    stage = _native_in(_receiver_spec(tmp_path, {"adaptive": True, "max_ms": 300}))
+
+    assert stage["paced_hold_topic"] == "/camera/image/ffmpeg/paced/hold_ms"
+
+
+def test_an_unpaced_link_names_no_pacer(tmp_path: Path) -> None:
+    """Nothing holds this stream, so nothing may be subtracted from its age."""
+    stage = _native_in(_receiver_spec(tmp_path, None))
+
+    assert "paced_hold_topic" not in stage
+
+
+def test_a_pacer_kept_off_the_display_path_explains_nothing(tmp_path: Path) -> None:
+    """`republish: unpaced` decodes the arrived stream; its age is all link."""
+    stage = _native_in(_receiver_spec(tmp_path, {"adaptive": True, "republish": "unpaced"}))
+
+    assert "paced_hold_topic" not in stage