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

{rosotacom_dev-2.5.dev51 → rosotacom_dev-2.5.dev53}/.github/workflows/nightly-e2e.yml

@@ -108,6 +108,7 @@ jobs:
           - cyclone-local-zenoh-ros2dds-ota
           - cyclone-ota
           - fastdds
+          - fastdds-default
           - zen-endpoints
     steps:
       - name: Check out repository

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev51
+Version: 2.5.dev53
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -309,6 +309,24 @@ rosotacom start 1_heartbeat --identity b \
   --peer-address a=10.0.0.10 --peer-address b=10.0.0.11
 ```
 
+Before `start` stops a conflicting container, writes an instance, or builds an
+image, it verifies that the selected identity's address belongs to this host and
+that the route to the other peer selects that address as its source. A missing
+VPN/data-plane interface or a route through the wrong network therefore fails
+without disturbing a working session. Run the same check on its own with
+`preflight`; deployments that require the other host to be online already can
+also make three bounded ICMP probes mandatory:
+
+```bash
+rosotacom preflight 1_heartbeat --identity a \
+  --peer-address a=10.0.0.10 --peer-address b=10.0.0.11 \
+  --require-peer-reachable
+```
+
+Peer reachability is opt-in because some valid networks block ICMP and peers may
+be started in either order. `rosotacom start` accepts the same
+`--require-peer-reachable` policy when a deployment does require it.
+
 `rosotacom` reads the static session input and creates generated files under `session-instances/<date>/<session>_<timestamp>_<id>/config/`, including per-peer plugin/session specs, topic lists, optional QoS, and optional `domain_bridge.yaml`. Catmux pane output is logged under the same instance in `logs/<peer>/catmux/`.
 
 What else a run leaves under `logs/<peer>/`, and which file to open first when a
@@ -580,6 +598,13 @@ the ssh client's own argv apart, and a transport that promises no more than
 `-t` and `-o BatchMode=yes` are dropped rather than forwarded. They are options
 of one client, and a transport that is not ssh never agreed to understand them.
 
+The same four options — `--peer-checkout`, `--peer-exec`, `--install-mode`,
+`--install-pin` — are on every `ota-benchmark` genre, not just `ota-smoke`. A
+measurement is the last thing that should require a shell on the peer: the
+whole point of a narrower transport is that the runs which touch a machine
+repeatedly can go through it, and a benchmark touches it far more often than a
+smoke test does.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.5.dev51 → rosotacom_dev-2.5.dev53}/README.md

@@ -264,6 +264,24 @@ rosotacom start 1_heartbeat --identity b \
   --peer-address a=10.0.0.10 --peer-address b=10.0.0.11
 ```
 
+Before `start` stops a conflicting container, writes an instance, or builds an
+image, it verifies that the selected identity's address belongs to this host and
+that the route to the other peer selects that address as its source. A missing
+VPN/data-plane interface or a route through the wrong network therefore fails
+without disturbing a working session. Run the same check on its own with
+`preflight`; deployments that require the other host to be online already can
+also make three bounded ICMP probes mandatory:
+
+```bash
+rosotacom preflight 1_heartbeat --identity a \
+  --peer-address a=10.0.0.10 --peer-address b=10.0.0.11 \
+  --require-peer-reachable
+```
+
+Peer reachability is opt-in because some valid networks block ICMP and peers may
+be started in either order. `rosotacom start` accepts the same
+`--require-peer-reachable` policy when a deployment does require it.
+
 `rosotacom` reads the static session input and creates generated files under `session-instances/<date>/<session>_<timestamp>_<id>/config/`, including per-peer plugin/session specs, topic lists, optional QoS, and optional `domain_bridge.yaml`. Catmux pane output is logged under the same instance in `logs/<peer>/catmux/`.
 
 What else a run leaves under `logs/<peer>/`, and which file to open first when a
@@ -535,6 +553,13 @@ the ssh client's own argv apart, and a transport that promises no more than
 `-t` and `-o BatchMode=yes` are dropped rather than forwarded. They are options
 of one client, and a transport that is not ssh never agreed to understand them.
 
+The same four options — `--peer-checkout`, `--peer-exec`, `--install-mode`,
+`--install-pin` — are on every `ota-benchmark` genre, not just `ota-smoke`. A
+measurement is the last thing that should require a shell on the peer: the
+whole point of a narrower transport is that the runs which touch a machine
+repeatedly can go through it, and a benchmark touches it far more often than a
+smoke test does.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.5.dev51 → rosotacom_dev-2.5.dev53}/deployment-configuration.md

@@ -85,6 +85,29 @@ Precedence is explicit:
 All logical peers must resolve to addresses before a session starts. Session
 definitions do not accept physical addresses or SSH targets.
 
+## Data-plane preflight
+
+`rosotacom start` checks the resolved bindings against the host before it stops
+or creates containers:
+
+1. The selected identity's IPv4 address must be assigned locally.
+2. `ip route get` for the other peer must select that same address as its
+   source.
+
+This makes an absent VPN/interface, a wrong identity, and a route escaping over
+another network startup errors instead of silent communication failures. Inspect
+the result without starting anything:
+
+```bash
+rosotacom preflight SESSION --identity PEER
+```
+
+Add `--require-peer-reachable` to `preflight` or `start` when this deployment
+also requires three bounded ICMP probes to succeed. Reachability is not the
+global default: ICMP can be intentionally filtered, and valid peers can be
+started in either order. Docker-isolated local smoke networks use their own
+network lifecycle and bypass this host data-plane check.
+
 ## Project selection and completion
 
 The nearest `rosotacom.yaml` is discovered upward from the current directory.

{rosotacom_dev-2.5.dev51 → rosotacom_dev-2.5.dev53}/docs/findings/README.md

@@ -28,6 +28,9 @@ living verification hook.
 
 ## Findings
 
+- [Sender-side transit rows made a dead link report zero loss](sender-rows-make-a-dead-link-look-loss-free.md) - `delivered = rows - lost` counted the sender's own `sent` rows as deliveries, so a topic the receiver never saw summarised as `delivered == expected` at 0.0% loss, with the publisher's timer reported as arrival spacing.
+- [A bridge that learns types from the graph cannot use a transport that does not carry the graph](graph-derived-types-block-a-non-graph-transport.md) - over `zenoh_ros2dds` the payload topic never arrived in either run: the bridge routes a topic once a local reader exists and the reader waited for the bridge, leaving only `Pending=1` in a log.
+- [A Fast DDS datagram cap stops every message larger than it](fastdds-datagram-cap-drops-large-samples.md) - copying CycloneDDS's 1200 B fragment size into the Fast DDS OTA profile makes every sample above the cap never arrive, at 1200 B and at 8192 B, sync and async — while the 84 B heartbeat keeps flowing at 10 Hz.
 - [A lost keyframe silences exactly the next gop_size−2 deltas](keyframe-loss-kills-the-next-deltas.md) - libavcodec emits nothing for them, the last delta decodes with artifacts, the next keyframe restores clean decode; a lost delta never blocks decode — so the display hole is gop_size × frame period, deterministically.
 - [Oversubscription queues — it does not lose until the queue itself dies](oversubscription-queues-not-losses.md) - 16% over an emulated cap climbed one-way delay 340 → 3250 ms across twelve bins with zero loss in every one; the losses arrived only when the queue died, all at once.
 - [Best-effort reordering becomes reader-side loss, independent of history depth](reorder-becomes-reader-loss.md) - under pure delay jitter a Cyclone best-effort reader discards every overtaken sample (57% at 100 Hz under 50+-45 ms), delivery stays strictly monotonic, and depth 50 loses the same as depth 1.

rosotacom_dev-2.5.dev53/docs/findings/fastdds-datagram-cap-drops-large-samples.md

@@ -0,0 +1,89 @@
+# A Fast DDS Datagram Cap Stops Every Message Larger Than It
+
+## Claim
+
+Setting `<maxMessageSize>` on a Fast DDS UDPv4 transport to a value below a
+sample's serialized size makes that sample **never arrive** through the OTA
+pipeline — not "arrive fragmented", not "arrive with loss". Messages that fit
+inside the cap keep flowing at full rate on the same link, which is what makes
+this dangerous: an 84 B heartbeat crossing at 10 Hz with 0.0% loss is a link
+that looks alive from every direction except the one that matters.
+
+The obvious reason to set it is symmetry with CycloneDDS, whose OTA profile
+carries this link at `FragmentSize`/`MaxMessageSize` 1200 B and works. The
+symmetry does not transfer: on ROS 2 Kilted with Fast DDS 3.2.4 the cap is the
+single knob that breaks the link, at 1200 B and at 8192 B, with a synchronous
+writer and with an asynchronous one.
+
+## Setup
+
+- Host pair / topology: one host, the packaged local smoke rig — two
+  communication containers on their own Docker network, split ROS domains
+  (peer 50, peer 51, OTA 52) with the stock `domain_bridge` between them. The
+  same failure was first seen across two machines over a VPN; one host
+  reproduces it, so nothing private is needed.
+- Session: a two-peer session with a `com_msgs/msg/SizedPayload` stream at
+  12000 B and 10 Hz on the loaded direction plus the echo heartbeat, OTA QoS
+  best_effort / depth 1 / lifespan 0.7 (the deployed shape).
+- rosotacom SHA: measured at `6e4b748`; re-runs record theirs.
+- Profile: none for the bisect — the failure needs no impairment, which is what
+  makes it attributable to the configuration rather than to the link.
+- Seed policy: deterministic (no netem, no random load), `n=1` per variant; the
+  effect is present/absent, not a distribution.
+
+## Evidence
+
+Evidence grade: single-host reproduction on packaged material, one variant per
+run, read from the receiving peer's own `status.txt`.
+
+Each knob of the tuned profile was added to the working `fastdds_unicast.xml`
+one at a time (2026-08-19):
+
+| added to fastdds_unicast.xml | 12 kB stream at the receiver |
+|---|---|
+| interface allowlist (127.0.0.1 + OTA address) | FLOWING 10.0 Hz, 0.0% loss |
+| loopback locators (default / metatraffic / initial peers) | FLOWING 10.0 Hz |
+| `maxInitialPeersRange` 10 | FLOWING 10.0 Hz |
+| discovery lease / announcement | FLOWING 10.0 Hz |
+| socket buffer sizes (1 MB / 4 MB) | FLOWING 10.0 Hz |
+| `non_blocking_send` | FLOWING 10.0 Hz |
+| `publishMode` ASYNCHRONOUS | FLOWING, degraded: 9.3 Hz at 285 ms |
+| **`maxMessageSize` 1200** | **IDLE — nothing delivered** |
+| **`maxMessageSize` 8192** | **IDLE — nothing delivered** |
+| **`maxMessageSize` 1200 + ASYNCHRONOUS** | **IDLE — nothing delivered** |
+
+The heartbeat crossed at 10 Hz with 0.0% loss in every one of those runs,
+including the three that delivered no payload at all.
+
+Two nearby observations, both of which cost time before the bisect narrowed it:
+
+- Two Fast DDS participants in two containers, with the capped profile and
+  nothing else running, DO exchange 12 kB and 38 kB samples (57–59 of 60). The
+  cap only breaks the full pipeline, where the sample crosses a domain bridge
+  and an OTA bridge, so an isolated transport probe will report the cap as
+  harmless.
+- Asynchronous publication does not rescue it, which rules out the documented
+  "a synchronous writer cannot fragment" explanation as the whole story.
+
+Verification: manual: run the packaged smoke for a session whose OTA side names
+`fastdds_tuned.xml`, then again for one that adds `<maxMessageSize>1200` to it,
+and read `logs/<receiver>/status/status.txt`; the payload stage is FLOWING in
+the first and IDLE in the second while the heartbeat is FLOWING in both. The
+shipped profiles are pinned against the cap by
+`tests/unit/test_ota_link_configs.py::test_only_cyclone_caps_the_datagram_and_fast_dds_must_not`.
+
+## Status
+
+confirmed, 2026-08-19.
+
+## Publication notes
+
+This is why "the OTA middleware is a configuration choice" needs measuring
+rather than reasoning: the two profiles that look like translations of each
+other are not, and the failure mode of the wrong translation is a link that
+passes a heartbeat check. Consequence for the transport comparison: Fast DDS
+lets IP fragment a large sample here where CycloneDDS sends RTPS fragments, so
+the two differ in what a lost packet costs and in what the tunnel has to
+reassemble — the measured OpenVPN barrier on the operator's path is around
+110 kB per message. Report Fast DDS numbers with that difference stated, not as
+a like-for-like transport swap.

rosotacom_dev-2.5.dev53/docs/findings/graph-derived-types-block-a-non-graph-transport.md

@@ -0,0 +1,79 @@
+# A Bridge That Learns Types From The Graph Cannot Use A Transport That Does Not Carry The Graph
+
+## Claim
+
+`PubSubPair` resolved a stage's message type from
+`get_topic_names_and_types()`, so it could only create its endpoints once
+somebody else had created the matching one. On a DDS OTA link that is invisible
+— the remote writer is in the same domain, so the graph knows it. Over the
+zenoh DDS bridge (`rmw.ota: zenoh_ros2dds`) it is a deadlock: the bridge
+creates a subscriber route for a topic only once a **local DDS reader** exists,
+and the reader was waiting for the bridge to route a publisher into the graph.
+Neither ever happens, the payload topic never arrives, and the only trace is one
+word in a log line — `Initialized 1 pair(s). Pending=1`.
+
+The heartbeat escapes it because the receiving peer's bridge sees the remote
+liveliness token for it early enough to create the route before the reader is
+needed; the wrapped payload topic does not. So the observable is again a link
+that carries the small topic and silently drops the big one.
+
+## Setup
+
+- Host pair / topology: two machines over a VPN, `rmw.ota: zenoh_ros2dds`
+  (local cyclone), split ROS domains, one 12 kB `SizedPayload` stream at 10 Hz
+  plus the echo heartbeat.
+- rosotacom SHA: observed at `6e4b748` (before the fix), fixed in `48d84dc`.
+- Profile: the drive-derived loss process; the effect is not a loss effect and
+  reproduced identically in both runs under it.
+- Seed policy: not applicable — present/absent, `n=2` runs, both failing the
+  same way.
+
+## Evidence
+
+Evidence grade: two live two-machine runs, read from the receiving peer's node
+logs and from the zenoh bridge's own routing log.
+
+Receiving peer, `bridge_in` (2026-08-19):
+
+```
+[PubSubPair] Created: sub='/ota/b/heartbeat_b' ...
+[PubSubPair] Created: sub='/ota/b/cam_like/ota_stamped' ...
+[PubSubPair] Initialized: sub='/ota/b/heartbeat_b' type='com_msgs/msg/EchoHeartbeat'
+[bridge_in] Initialized 1 pair(s). Pending=1
+```
+
+Receiving peer, `zenoh_bridge_ros2dds`, for the whole run:
+
+```
+routes_mgr: Route Subscriber (Zenoh:ota/b/heartbeat_b -> ROS:/ota/b/heartbeat_b) created
+```
+
+— and no such line for `ota/b/cam_like/ota_stamped`, while the sending peer had
+created its publisher route for exactly that key. Delivered payload messages in
+both runs: 0 of ~810 sent.
+
+The fix removes the dependency rather than the symptom: every session now writes
+`<peer>/topic_types.yaml` (`<stage topic>: <message type>` for every stage that
+peer takes part in, derived from the same pipeline description the status node
+uses), the bridge and relay nodes read it, and the graph is consulted only for
+what the file does not name.
+
+Verification: `python -m pytest -q tests/unit/test_pub_sub_pair_types.py` — a
+pair with a declared type creates its endpoints against an empty graph, a pair
+without one still reads the graph, and a pair with neither stays pending.
+`tests/unit/test_ota_link_configs.py::test_every_peer_gets_the_stage_types_its_bridges_need`
+pins that the file is generated for every peer of every session.
+
+## Status
+
+confirmed, 2026-08-19.
+
+## Publication notes
+
+Worth stating in any "the transport is a configuration choice" claim: a
+pipeline can depend on a transport property nobody wrote down — here, that the
+transport propagates the ROS graph and not only the data. DDS does, the zenoh
+DDS bridge does not, and the dependency only shows up as a topic that never
+arrives. The general lesson is that a contract known at generation time should
+be handed to the runtime rather than rediscovered from the runtime, which is
+also what makes bring-up order-independent.

rosotacom_dev-2.5.dev53/docs/findings/sender-rows-make-a-dead-link-look-loss-free.md

@@ -0,0 +1,59 @@
+# Sender-Side Transit Rows Made A Dead Link Report Zero Loss
+
+## Claim
+
+`summarize_transit_records` counted `delivered = rows − lost`. Sender-side
+transit rows carry the status `sent` and are written whether or not anything
+arrives, so a topic that the receiving peer never saw at all summarised as
+`delivered == expected`, `loss_pct 0.0` — with the sender's own publication
+cadence reported as the arrival spacing. The most dangerous shape a wrong number
+can take: a link that delivered nothing scored better than one that delivered
+96% of its messages.
+
+Delivery is a receiver fact. Rows still `sent` after the join are `unconfirmed`;
+`loss_pct` is `None` when no receiver accounted for the topic at all; and an
+oracle reads that `None` as the worst case rather than as zero.
+
+## Setup
+
+- Host pair / topology: not a transport property — the summary is a pure
+  function of collected records, so the reproduction is a unit test over
+  synthetic rows. It was found on a two-machine run whose OTA transport
+  delivered nothing.
+- rosotacom SHA: present up to `6e4b748`, fixed in `730ddf5`.
+- Profile: none — the defect is in the accounting, not in the link.
+- Seed policy: not applicable, deterministic.
+
+## Evidence
+
+Evidence grade: unit-level, deterministic, plus the live run that exposed it.
+
+Live (2026-08-19, `rmw.ota: zenoh_ros2dds` over two machines): the sending peer
+wrote 816 `outbound`/`sent` rows, the receiving peer wrote 5 rows and no
+delivery at all. The run's `result.json` reported `delivered 807, expected 807,
+loss_pct 0.0` for that topic, with inter-arrival p05/p95 of 102/104 ms — the
+publisher's own timer, not an arrival distribution. The receiver's `status.txt`
+for the same run said `ota_recv ABSENT/GRAPH pub=0` and `com_in IDLE`.
+
+The window mattered as much as the number: this only became reachable when
+sender-side transit rows landed (issue #294). Before that, a topic with no
+receiver rows had no rows at all and simply did not appear.
+
+Verification: `python -m pytest -q tests/unit/test_transit.py -k sender_rows`
+— sender rows alone report `delivered 0`, `unconfirmed 3` and `loss_pct None`,
+and a mixed set counts only the receiver's verdicts.
+`tests/unit/test_benchmark.py::test_an_unknown_loss_figure_is_read_as_the_worst_case`
+pins that an oracle does not pass on the `None`.
+
+## Status
+
+confirmed, 2026-08-19.
+
+## Publication notes
+
+A measurement pipeline that gains a second observer gains a way to be
+confidently wrong: the new rows were real, the join was correct, and the
+aggregate stopped meaning what its name said. Worth citing whenever a loss
+figure is quoted from an automated run — state which side observed it. The
+general rule the fix encodes: an aggregate over rows from two observers must say
+which observer each row came from before it counts anything.

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

@@ -167,8 +167,49 @@ not override `RMW_IMPLEMENTATION` and relies on the ambient ROS 2 defaults — n
 Per-side config blocks:
 
 - DDS implementations (`cyclone`, `fastdds`) accept:
-  - `config: <template>` — template file under `ws/ota_configs/` (e.g. `fastdds_v1.xml`, `cyclonedds.xml`, `fastdds_easy_mode.xml`). Omit to use the RMW's built-in defaults.
-  - `easy_mode_ip: <string>` — only honored by `fastdds_easy_mode.xml`; defaults to the first resolved peer address.
+  - `config: <template>` — template file under `ws/ota_configs/`
+    (`cyclonedds_tuned.xml`, `cyclonedds_minimal.xml`,
+    `cyclonedds_local_participants.xml`, `fastdds_tuned.xml`,
+    `fastdds_unicast.xml`, `fastdds_easy_mode.xml`).
+  - `easy_mode_ip: <string>` — resolved into a template's `#easy_mode_ip`
+    placeholder; defaults to the first resolved peer address. Only
+    `fastdds_easy_mode.xml` uses it.
+
+  `fastdds_easy_mode.xml` is the discovery alternative: Fast DDS 3.1 spawns or
+  reuses one Discovery Server per host and points the participant at the peer's
+  server too, so two hosts find each other with no multicast and no per-peer
+  locator list. It fails differently from `fastdds_tuned.xml` rather than
+  better — an explicit peer list cannot discover what it was not told about,
+  while easy mode depends on a server process being reachable on 11811 — which
+  is why both are packaged. Neither caps the datagram (see above); easy mode
+  expresses its transport settings as `<builtinTransports …>` attributes,
+  because replacing the transports outright would take its discovery path with
+  them.
+
+  **On the OTA side, omitting `config` is not "no configuration".** Each
+  implementation has a default template, and both defaults are the link-ready
+  one: `cyclone` → `cyclonedds_tuned.xml`, `fastdds` → `fastdds_tuned.xml`.
+  That is what makes `shared.rmw` an interchangeable choice — a session names a
+  middleware and gets unicast discovery with the OTA interface pinned either
+  way, rather than one middleware that survives a cellular tunnel and one that
+  has to be configured into surviving it. `fastdds_unicast.xml` is the earlier,
+  locator-only configuration, kept for a run that wants to measure the
+  difference.
+
+  The two defaults are **not** identical in what they put on the wire, and the
+  difference is deliberate. CycloneDDS fragments at the RTPS layer (1200 B);
+  Fast DDS hands a large sample to the kernel as one datagram and lets IP
+  fragment it. Writing the same cap into the Fast DDS profile is the obvious
+  move and it takes the link down: measured on the bench pair (2026-08-18/19,
+  ROS 2 Kilted, Fast DDS 3.2.4) a `maxMessageSize` below the sample size stops
+  the sample from ever arriving — at 1200 B and at 8192 B, synchronous writer
+  and asynchronous — while an 84 B heartbeat on the same link keeps flowing.
+  Plan the payload accordingly: the measured OpenVPN barrier on this path is
+  around 110 kB per message.
+
+  On the **local** side, omitting `config` really is no configuration: no
+  template is applied and no `CYCLONEDDS_URI` / `FASTDDS_DEFAULT_PROFILES_FILE`
+  is exported.
 
   On the **local** side of a busy machine, set
   `config: cyclonedds_local_participants.xml`. Cyclone allows 33 participants
@@ -179,10 +220,22 @@ Per-side config blocks:
   interface and sets no peer list, because local discovery must keep working.
   The OTA templates are not usable on the local side for exactly that reason.
 - `zenoh_connect_endpoints` (native, OTA side only; `zenoh` is still accepted as a legacy OTA alias) accepts:
+  - `transport: tcp|udp` — the inter-host transport between the two routers.
+    Default `tcp`. On a lossy link TCP is the wrong choice for a best-effort
+    stream: one retransmit stalls everything queued behind it, which turns a
+    cellular dip into seconds of latency instead of one lost sample. The
+    listening router keeps `tcp/[::]:7447` whatever this is set to, because
+    every rmw_zenoh node on that host is a zenoh *client* of it over
+    `tcp/localhost:7447`.
   - `main_peer: <peer_key>` — the peer whose zenoh router listens. Defaults to the first peer declared under `peers:`.
   - `main_port: 7447` — listening port. Default `7447`.
 - `zenoh_ros2dds` (bridge) accepts (OTA side only):
-  - `transport: udp|tcp` — default `udp`.
+  - `transport: udp|tcp` — default `tcp`, measured rather than assumed. On the
+    bench pair (2026-08-19, the 2026-08-17 drive's loss process, 12 kB at 10 Hz)
+    the UDP bridge delivered in one run of five and lost 66% of that one, while
+    the TCP bridge delivered in every run at ~1% loss with the lowest median
+    latency in the campaign. UDP stays available for a link where TCP's
+    head-of-line blocking costs more than its retransmission buys.
   - `main_peer: <peer_key>` — defaults to the first peer.
   - `main_port: 7447` — default `7447`.
 
@@ -227,6 +280,22 @@ topics to/from zenoh. The local graph still speaks DDS, so `rmw.local` must be
 - `zen_pub_allow` / `zen_sub_allow` are derived from peer `com-name`s (`/ota/<com-name>/.*`).
 - `zen_qos_pub` is derived from per-topic `zen_qos:` entries and baked into the generated `<peer>/plugin.yaml`.
 
+#### Generated per peer: `topic_types.yaml`
+
+Every session writes `<peer>/topic_types.yaml` — `<stage topic>: <message
+type>` for every stage that peer takes part in — and the bridge and relay nodes
+read it. It is generated whether or not `use_status_overview` is set, and is
+derived from the same pipeline description the status node uses, so the two
+cannot disagree about what a stage is called.
+
+It exists because the alternative was the ROS graph, and the graph makes an
+endpoint's creation depend on somebody else having created the matching one
+first. Over a transport that carries data but not the graph — `rmw.ota:
+zenoh_ros2dds`, where the bridge routes a topic only once a local DDS reader
+exists — that is a deadlock, and a silent one: the receiving peer logs
+`Initialized 1 pair(s). Pending=1` and the topic simply never arrives. The graph
+is still consulted for anything the file does not name.
+
 #### Domain bridging
 
 If `shared.ota_domain_id` and `peer_settings.<peer>.domain_id` are both set and
@@ -421,6 +490,21 @@ Each entry is either:
   - `expect` (optional mapping); `smoke_probe: false` keeps the topic in the
     generated contract but excludes it from synthetic local-smoke probes
 
+    Two `expect` keys describe the *synthetic source* rather than the contract,
+    for the runs (local smoke, `ota-smoke`, OTA benchmark genres) that drive a
+    session with generated traffic instead of a replay:
+
+    - `smoke_native_hz` — publish the native topic at this rate instead of
+      deriving it from the `hz` bounds. Needed wherever the pipeline changes the
+      rate (`drop`, `throttle_hz`, `trickle_hz`), because the asserted rate is
+      the delivered one and the source has to run faster.
+    - `smoke_native_bytes` — the payload size for a
+      `com_msgs/msg/SizedPayload` topic (default 66000). The size belongs to the
+      load a session wants driven: comparing two OTA middlewares, or two
+      profiles, means holding the payload at a chosen size — a 38 kB camera
+      keyframe, say — rather than at whatever constant the driver carries. It is
+      also what the receiving side asserts, so both ends stay consistent.
+
 In split-domain mode the generator must emit a standard ROS 2 `domain_bridge` YAML with explicit
 message types for `/com/...` topics. For that reason, user-defined topic entries need `type:`.
 The auto-generated heartbeat topic is the only exception because its type is known by the generator.

{rosotacom_dev-2.5.dev51 → rosotacom_dev-2.5.dev53}/src/rosotacom/benchmark.py

@@ -191,9 +191,19 @@ def oracle_passes(loss_pct: float, latency_ms: float | None, thresholds: OracleT
     return loss_pct <= thresholds.max_loss_pct and latency_ms <= thresholds.max_latency_ms
 
 
+def _oracle_loss_pct(value: Any) -> float:
+    """A topic's loss for an oracle, with "unknown" read as the worst case.
+
+    `summarize_transit_records` reports `None` when no receiving peer accounted
+    for the topic at all. That is not zero loss; it is no evidence, and an
+    oracle that let it pass would turn a dead link into a green run.
+    """
+    return 100.0 if value is None else float(value)
+
+
 def oracle_passes_topic(topic_summary: dict[str, Any], thresholds: OracleThresholds) -> bool:
     """Apply the oracle to one topic of ``transit.summarize_transit_records`` output."""
-    loss_pct = float(topic_summary.get("loss_pct", 100.0))
+    loss_pct = _oracle_loss_pct(topic_summary.get("loss_pct", 100.0))
     latency = (topic_summary.get("ota_hop_ms") or {}).get(thresholds.latency_quantile)
     return oracle_passes(loss_pct, None if latency is None else float(latency), thresholds)
 
@@ -323,7 +333,7 @@ def evaluate_bag_run(
         lost = data.get("lost")
         reordered = data.get("reordered")
         run_expected = data.get("expected")
-        loss_pct = float(data.get("loss_pct", 100.0)) if data else 100.0
+        loss_pct = _oracle_loss_pct(data.get("loss_pct", 100.0)) if data else 100.0
         latency_p95 = (data.get("ota_hop_ms") or {}).get(quantile) if data else None
         jitter_p95 = (data.get("jitter_ms") or {}).get("p95") if data else None
         latency_val = None if latency_p95 is None else float(latency_p95)