rosotacom-dev 2.5.dev53__tar.gz → 2.5.dev55__tar.gz

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/PKG-INFO

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

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/docs/testing.md

@@ -25,6 +25,41 @@ slice. The full local suite also runs nightly, as does the blocking benchmark
 regression matrix ([performance-bands.md](performance-bands.md)). The external
 OTA gate remains operator-started before a promotion to `main`.
 
+## Every read has a producer
+
+`tests/contract/test_generated_topics_have_a_producer.py` generates every
+example session and asserts that each topic a node is *configured to read* is
+either written by another node on the same peer or a stage that peer's own
+`pipeline_spec.yaml` models. Writes are deliberately not required to be stages:
+a node may publish for a human (`NOR` restores `/tf`, the pacer publishes
+`budget_ms`) and none of that is something the link promises to deliver.
+
+It exists because this project's characteristic defect — #12, #259, #276, #304 —
+is always the same one: a ROS node advertises its output whether or not its
+input exists, so a node pointed at a name nobody publishes starts, stays up,
+reports healthy and delivers nothing. #304 was the first of the four caught by
+any check at all, and that check was a six-minute Docker slice covering one
+example. This one runs the same corpus in about a second.
+
+Two guards keep it honest, and both fail loudly rather than degrading:
+
+- every parameter `session_plugin_base.yaml` declares must be classified in the
+  check, so a new window cannot arrive unmodelled and be silently covered;
+- the composed names the check derives (`<topic>/paced`, `<topic>/drop1of2`, …)
+  are asserted to be the forms the template itself composes.
+
+It also pins **which window families the examples actually exercise**. Today
+`fb`, `ipx`, `nor` and `pace` are exercised by no example, so the check models
+them unverified — `pace` most notably, since the playout pacer is deployed on a
+real link. Tracked in
+[#307](https://github.com/develNor/ros_communication_devcontainer/issues/307);
+adding an example that uses one of them is the way to close it.
+
+The check covers reads by nodes *the session configures*. It cannot see an
+application outside the session subscribing to a name the link no longer
+delivers — that half of #12 and #276 needs the consumer to be declared
+somewhere, and nothing declares it today.
+
 ## Expectations
 
 Per-topic `expect` blocks are behavioral contracts in `session-definition.yaml`.

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/session-configuration.md

@@ -674,6 +674,7 @@ Declaratively, add a `playout` block to the transport:
             target_ms: 350    # fixed budget when adaptive: false
             min_ms: 100       # adaptive clamp above the observed delay floor
             max_ms: 800
+            republish: paced  # paced (default) | unpaced | both
 ```
 
 The receiving peer then runs the pacer in its own `PACE` window against the
@@ -684,6 +685,33 @@ why `playout` requires `remote_republish`: without a republish the pacer's
 The sender's own preview decode (`local_republish`) is never paced — it reads
 the local copy of what was just encoded, so there is no jitter to absorb.
 
+##### `republish`: which stream reaches the display
+
+Pacing under an unchanged topic name is what keeps applications working, and it
+is also what makes the improvement invisible — nothing shows paced and unpaced
+together. `republish` names which stream the receiver decodes:
+
+| value | decodes | publishes |
+|---|---|---|
+| `paced` (default) | `<encoded>/paced` | `<encoded>/<remote_republish>` |
+| `unpaced` | `<encoded>` | `<encoded>/<remote_republish>` |
+| `both` | both | delivered as above, comparison on `<encoded>/unpaced/<remote_republish>` |
+
+**The delivered name is the same in all three.** Only what feeds the decode
+moves, so switching modes never changes what an application subscribes to.
+
+`unpaced` still runs the pacer: `/paced` and its `budget_ms` / `queue_depth`
+debug topics are published and recordable, they just do not reach the display.
+That is the A/B control — measure a pacer on a live link without changing what
+an operator sees.
+
+`both` runs the receiver's expensive stage twice (a codec decode plus, for
+`compressed`, a JPEG encode per frame) and adds one local topic; nothing extra
+crosses the link. It also consumes one of the four reverse-transport slots. It
+is a rehearsal and diagnosis switch — the comparison stream is deliberately not
+a status pipeline stage, because it is not something the link promises to
+deliver.
+
 The node also runs standalone against any packet stream:
 
 ```bash

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/src/rosotacom/resources/ws/session/content/base/session_plugin_base.yaml

@@ -230,22 +230,32 @@ parameters:
   it_4_foxglove_qmax: -1
   it_4_outgoing_suffix: # e.g. compressed (defaults to it_4_transport if not set)
 
+  # `irt_N_out_topic` overrides where a decode publishes. It exists so two slots
+  # can decode the *same* stream — the paced one under the name applications
+  # already subscribe to, an unpaced copy next to it for comparison
+  # (transport.playout.republish: both). Left unset, a decode publishes on
+  # ${irt_N_topic}/${irt_N_out_transport}, which is the only shape any session
+  # had before and the one every unpaced link still has.
   irt: false
   irt_1_topic: # e.g. /sensors/camera/front_wide/image_color
   irt_1_transport: # e.g. raw
   irt_1_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_1_out_topic: # overrides the output remap; defaults to ${irt_1_topic}/${irt_1_out_transport}
   irt_1_paced: # "true" -> decode reads ${irt_1_topic}/paced (playout pacer, PACE window)
   irt_2_topic: # e.g. /sensors/front_camera/image_raw/compressed
   irt_2_transport: # e.g. raw
   irt_2_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_2_out_topic: # overrides the output remap; defaults to ${irt_2_topic}/${irt_2_out_transport}
   irt_2_paced: # "true" -> decode reads ${irt_2_topic}/paced
   irt_3_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_3_transport: # e.g. raw
   irt_3_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_3_out_topic: # overrides the output remap; defaults to ${irt_3_topic}/${irt_3_out_transport}
   irt_3_paced: # "true" -> decode reads ${irt_3_topic}/paced
   irt_4_topic: # e.g. /sensor/front_camera/image_color/compressed
   irt_4_transport: # e.g. raw
   irt_4_out_transport: compressed # e.g. raw, compressed – determines the output remap format
+  irt_4_out_topic: # overrides the output remap; defaults to ${irt_4_topic}/${irt_4_out_transport}
   irt_4_paced: # "true" -> decode reads ${irt_4_topic}/paced
 
   # Receiver-side playout pacing (transport.playout in the session definition):
@@ -707,31 +717,35 @@ windows:
         - if [ '${irt_1_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_1_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_1_out_transport}"; fi
         - if [[ "${irt_1_paced}" != "None" ]]; then irt_in_topic="${irt_1_topic}/paced"; else irt_in_topic="${irt_1_topic}"; fi
+        - if [[ "${irt_1_out_topic}" != "None" ]]; then irt_out_topic="${irt_1_out_topic}"; else irt_out_topic="${irt_1_topic}/${irt_1_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish1 -p in_transport:=${irt_1_transport} -p out_transport:=${irt_1_out_transport}
-            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_1_topic}/${irt_1_out_transport})
+            --remap in/${irt_1_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_2_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_2_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_2_out_transport}"; fi
         - if [[ "${irt_2_paced}" != "None" ]]; then irt_in_topic="${irt_2_topic}/paced"; else irt_in_topic="${irt_2_topic}"; fi
+        - if [[ "${irt_2_out_topic}" != "None" ]]; then irt_out_topic="${irt_2_out_topic}"; else irt_out_topic="${irt_2_topic}/${irt_2_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish2 -p in_transport:=${irt_2_transport} -p out_transport:=${irt_2_out_transport}
-            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_2_topic}/${irt_2_out_transport})
+            --remap in/${irt_2_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_3_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_3_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_3_out_transport}"; fi
         - if [[ "${irt_3_paced}" != "None" ]]; then irt_in_topic="${irt_3_topic}/paced"; else irt_in_topic="${irt_3_topic}"; fi
+        - if [[ "${irt_3_out_topic}" != "None" ]]; then irt_out_topic="${irt_3_out_topic}"; else irt_out_topic="${irt_3_topic}/${irt_3_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish3 -p in_transport:=${irt_3_transport} -p out_transport:=${irt_3_out_transport}
-            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_3_topic}/${irt_3_out_transport})
+            --remap in/${irt_3_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}
       - commands:
         - if [ '${irt_4_topic}' = "None" ]; then exit; fi
         - if [[ "${irt_4_out_transport}" == "raw" ]]; then out_remap="out"; else out_remap="out/${irt_4_out_transport}"; fi
         - if [[ "${irt_4_paced}" != "None" ]]; then irt_in_topic="${irt_4_topic}/paced"; else irt_in_topic="${irt_4_topic}"; fi
+        - if [[ "${irt_4_out_topic}" != "None" ]]; then irt_out_topic="${irt_4_out_topic}"; else irt_out_topic="${irt_4_topic}/${irt_4_out_transport}"; fi
         - args=(ros2 run image_transport republish --ros-args -r __node:=irt_republish4 -p in_transport:=${irt_4_transport} -p out_transport:=${irt_4_out_transport}
-            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_4_topic}/${irt_4_out_transport})
+            --remap in/${irt_4_transport}:=${irt_in_topic} --remap ${out_remap}:=${irt_out_topic})
         - echo ${args[@]}
         - ${args[@]}

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

@@ -101,6 +101,44 @@ class TransportSpec:
     playout: Optional[Dict[str, Any]] = None
 
 
+#: What `transport.playout.republish` may say, and what each answer decodes.
+#: The delivered topic name is the same in all three -- only what feeds the
+#: decode moves, and `both` adds a second decode under a name of its own.
+PLAYOUT_REPUBLISH_MODES = ("paced", "unpaced", "both")
+PLAYOUT_REPUBLISH_DEFAULT = "paced"
+
+
+def playout_republish(playout: Dict[str, Any]) -> str:
+    """Which stream the receiver decodes, for a link that declares `playout`.
+
+    Only meaningful where a pacer runs. A link without `playout` has no paced
+    copy to read, so callers decide that case before asking -- passing None here
+    would answer 'paced' for a stream nothing paces.
+    """
+    return str((playout or {}).get("republish", PLAYOUT_REPUBLISH_DEFAULT))
+
+
+@dataclass
+class IrtSlot:
+    """One reverse-transport decode: what it reads, and where it publishes.
+
+    Four of these fit in the base plugin. Most links use one per direction, but
+    a comparison decode (`playout.republish: both`) is a second slot on the same
+    topic -- which is the only reason `out_topic` exists, since two decodes of
+    one stream would otherwise remap onto the same output name.
+    """
+
+    topic: str
+    ttype: str
+    out_transport: str
+    #: Set only for the slot that a pacer feeds; the pacer is configured from it.
+    playout: Optional[Dict[str, Any]] = None
+    #: Read '<topic>/paced' rather than '<topic>'.
+    reads_paced: bool = False
+    #: Override the output remap; None means '<topic>/<out_transport>'.
+    out_topic: Optional[str] = None
+
+
 @dataclass
 class TopicEntry:
     base: str
@@ -1746,7 +1784,7 @@ def _compute_pipeline(
         if playout_cfg is not None:
             if not isinstance(playout_cfg, dict):
                 raise ValueError(f"transport.playout must be a mapping for topic '{entry.base}'")
-            allowed = {"adaptive", "target_ms", "min_ms", "max_ms"}
+            allowed = {"adaptive", "target_ms", "min_ms", "max_ms", "republish"}
             unknown = sorted(set(playout_cfg) - allowed)
             if unknown:
                 raise ValueError(
@@ -1769,6 +1807,15 @@ def _compute_pipeline(
                 raise ValueError(f"transport.playout.max_ms must be >= min_ms for topic '{entry.base}'")
             if "adaptive" in playout_cfg and not isinstance(playout_cfg["adaptive"], bool):
                 raise ValueError(f"transport.playout.adaptive must be a boolean for topic '{entry.base}'")
+            if "republish" in playout_cfg and playout_cfg["republish"] not in PLAYOUT_REPUBLISH_MODES:
+                raise ValueError(
+                    f"transport.playout.republish for topic '{entry.base}' is "
+                    f"{playout_cfg['republish']!r}; allowed: {list(PLAYOUT_REPUBLISH_MODES)}. "
+                    "'paced' decodes the paced copy (the default), 'unpaced' runs the pacer "
+                    "without putting it on the display path, and 'both' adds a second decode "
+                    "on '<encoded>/unpaced/<transport>' for comparison. The delivered topic "
+                    "name is the same in all three."
+                )
             playout = dict(playout_cfg)
 
         params = {k: v for k, v in t.items() if k not in ("type", "playout", *republish_keys)}
@@ -2781,11 +2828,12 @@ def func(
             nor_items.append((base, suffix))
 
         # Hard limits from session_plugin_base.yaml.
-        def _assert_max(label: str, items: List[Any], limit: int) -> None:
+        def _assert_max(label: str, items: List[Any], limit: int, note: str = "") -> None:
             if len(items) > limit:
                 raise RuntimeError(
                     f"peer '{local}': too many '{label}' entries ({len(items)}). "
                     f"The base session plugin supports at most {limit}."
+                    + (f" Note: {note}." if note else "")
                 )
 
         _assert_max("drp", drp_items, 8)
@@ -3319,31 +3367,58 @@ def func(
         # The sender's own preview decode is never paced: it reads the local
         # copy of what it just encoded, so there is no network jitter to
         # absorb. Playout pacing exists on the receiving side only.
-        irt_all: List[Tuple[str, str, str, Optional[Dict[str, Any]]]] = []
+        irt_all: List[IrtSlot] = []
         for t, tspec in irt_items_local:
             assert tspec is not None
-            irt_all.append((t, tspec.type, str(tspec.local_republish), None))
-        irt_all.extend(
-            (topic, tspec.type, str(tspec.remote_republish), tspec.playout) for topic, tspec in irt_items_remote
+            irt_all.append(IrtSlot(t, tspec.type, str(tspec.local_republish)))
+        for topic, tspec in irt_items_remote:
+            out_transport = str(tspec.remote_republish)
+            if tspec.playout is None:
+                # No pacer on this link: the decode reads what arrived. Asking
+                # it for '<topic>/paced' would give it a name nothing publishes,
+                # which advertises an output and then never fills it.
+                irt_all.append(IrtSlot(topic, tspec.type, out_transport))
+                continue
+            mode = playout_republish(tspec.playout)
+            # The decode an application reads keeps its name in every mode; only
+            # what feeds it moves. `unpaced` still runs the pacer -- it publishes
+            # '<topic>/paced' and its debug topics for measurement -- and simply
+            # does not put it on the display path.
+            irt_all.append(
+                IrtSlot(topic, tspec.type, out_transport, playout=tspec.playout, reads_paced=mode != "unpaced")
+            )
+            if mode == "both":
+                # The comparison branch: same stream, undelayed, under a name of
+                # its own. `<topic>/unpaced` is a valid image_transport base, so
+                # a viewer subscribes to it exactly like the delivered one.
+                irt_all.append(
+                    IrtSlot(topic, tspec.type, out_transport, out_topic=f"{topic}/unpaced/{out_transport}")
+                )
+        _assert_max(
+            "irt",
+            irt_all,
+            4,
+            note="a `playout.republish: both` comparison decode consumes a slot of its own",
         )
-        _assert_max("irt", irt_all, 4)
         if irt_all:
             items2 = [("irt", True)]
-            for i, (topic, _ttype, _out_transport, _playout) in enumerate(irt_all, 1):
-                items2.append((f"irt_{i}_topic", topic))
-            for i, (_topic, ttype, out_transport, playout) in enumerate(irt_all, 1):
-                items2.append((f"irt_{i}_transport", ttype))
-                items2.append((f"irt_{i}_out_transport", out_transport))
-                if playout is not None:
+            for i, slot in enumerate(irt_all, 1):
+                items2.append((f"irt_{i}_topic", slot.topic))
+            for i, slot in enumerate(irt_all, 1):
+                items2.append((f"irt_{i}_transport", slot.ttype))
+                items2.append((f"irt_{i}_out_transport", slot.out_transport))
+                if slot.out_topic is not None:
+                    items2.append((f"irt_{i}_out_topic", slot.out_topic))
+                if slot.reads_paced:
                     # Points the decode's input remap at '<topic>/paced'; the
                     # pacer itself runs in the PACE window below.
                     items2.append((f"irt_{i}_paced", "true"))
             blocks.append(PluginBlock("irt", items2))
 
         paced_entries = [
-            (i, topic, ttype, playout)
-            for i, (topic, ttype, _out_transport, playout) in enumerate(irt_all, 1)
-            if playout is not None
+            (i, slot.topic, slot.ttype, slot.playout)
+            for i, slot in enumerate(irt_all, 1)
+            if slot.playout is not None
         ]
         if paced_entries:
             items_pace: List[Tuple[str, Any]] = [("pace", True)]

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/src/rosotacom_dev.egg-info/PKG-INFO

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

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/src/rosotacom_dev.egg-info/SOURCES.txt

@@ -304,6 +304,7 @@ src/rosotacom_dev.egg-info/scm_version.json
 src/rosotacom_dev.egg-info/top_level.txt
 tests/contract/test_benched_set_registry.py
 tests/contract/test_findings.py
+tests/contract/test_generated_topics_have_a_producer.py
 tests/contract/test_markdown_links.py
 tests/contract/test_ota_source_bundle.py
 tests/contract/test_package_metadata.py

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/src/rosotacom_dev.egg-info/scm_file_list.json

@@ -299,6 +299,7 @@
     "terminology.md",
     "tests/contract/test_benched_set_registry.py",
     "tests/contract/test_findings.py",
+    "tests/contract/test_generated_topics_have_a_producer.py",
     "tests/contract/test_markdown_links.py",
     "tests/contract/test_ota_source_bundle.py",
     "tests/contract/test_package_metadata.py",

{rosotacom_dev-2.5.dev53 → rosotacom_dev-2.5.dev55}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 53,
-  "node": "g05d5905a4728651003afe5bc2feb657a96a1d395",
+  "distance": 55,
+  "node": "gd772be38947b2d3b6d4fc5d45d9fa57da1e1723a",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-19"