rosotacom-dev 2.5.dev80__tar.gz → 2.5.dev82__tar.gz

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/PKG-INFO

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

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/docs/findings/README.md

@@ -40,6 +40,7 @@ living verification hook.
 - [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.
 - [Any transport element in a Fast DDS profile doubles every sample on the wire](a-transport-element-doubles-every-fastdds-sample.md) - 366 datagrams for 180 samples against 183 without it; `<builtinTransports>DEFAULT` is a no-op selection and doubles too, so the trigger is the element's presence — removing it takes the shipped OTA profile from 2.10x the payload to 1.04x at identical delivery.
 - [Lifespan is enforced by one DDS reader and not the other](lifespan-is-enforced-by-one-reader-and-not-the-other.md) - under the same 20% oversubscription both stacks queue alike (472 and 433 delivered at ~1.1-1.2 s); with `lifespan: 0.7` CycloneDDS is unchanged and delivers 9.1% inside the bound, while Fast DDS drops to 4 delivered and never exceeds 570 ms — the policy decides shown-vs-suppressed, not how long the wait is.
+- [A filling queue adds delay and no loss of its own](queueing-adds-delay-not-loss.md) - 18 bins of ramp from 0.5 to 5.6 s lose 0 of 558 on a clean link and 15 of 558 on one that drops 0.6 % of packets, which is the unshaped rate; the queue defers, the link loses, and the buffer ends it at 97 % of one bin.
 - [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.
 - [Jitter causes loss while bandwidth shortage builds latency](jitter-loss-bandwidth-latency.md) - 18 KB at 20 Hz separates jitter-induced loss from bandwidth-induced queueing.

rosotacom_dev-2.5.dev82/docs/findings/queueing-adds-delay-not-loss.md

@@ -0,0 +1,122 @@
+# A Filling Queue Adds Delay And No Loss Of Its Own
+
+## Claim
+
+Under oversubscription a queue converts the excess into delay and contributes
+**nothing** to the loss rate until it overflows. Capping an otherwise clean link
+15 % below the offer ramps one-way delay from 0.5 s to 5.6 s across eighteen
+consecutive one-second bins with **0 of 558** offered messages lost, and drops
+97 % of a bin only once the buffer is full. Repeating the same cap on a link
+that also drops 0.6 % of packets independently reproduces the identical ramp and
+loses 15 of 558 during it — 2.7 %, which is the unshaped link's own 2.51 % and
+not a milligram more.
+
+So "the queue lost it" is never the explanation. Whatever a filling queue loses,
+the link was losing anyway; what the queue adds is age. The corollary is the
+useful one: **loss and delay have to be read as two measurements, because the
+queue moves only one of them**, and a loss-based health verdict is blind to the
+whole of the second signal.
+
+## Setup
+
+- Host pair / topology: `tks-lamborghini`, rosotacom local benchmark mode using
+  the packaged example project; two peer containers on a private bridge, uplink
+  shaping via `tc` inside the peers' own netns (no host privileges).
+- rosotacom SHA: `c5ce52f` (harness), submodule `c2d2467`.
+- Profile: four conditions in one file, offer held at 1.035 Mbit/s throughout so
+  only the shaping differs.
+
+  | name | uplink |
+  |---|---|
+  | `q-clean` | `delay: 25ms` |
+  | `q-loss` | `delay: 25ms, loss: 0.6%` |
+  | `q-squeeze` | 10 s clean, 25 s at `rate: 900kbit`, 10 s clean |
+  | `q-squeeze-loss` | the same three steps, `loss: 0.6%` throughout |
+
+- Load: `--size-pattern 6x200B+1x28KB --rate-hz 31`, so one stream carries a
+  1-fragment and a 24-fragment class together and the size signature of the loss
+  is readable inside a single run.
+- Seed policy: `loss` is netem's own stochastic element; `n=1` per condition,
+  reported as the four-cell comparison rather than as a distribution.
+
+## Evidence
+
+Evidence grade: packaged-profile benchmark runs plus their per-bin timelines.
+
+```bash
+rosotacom benchmark probe --project src/rosotacom/resources/examples/rosotacom.yaml \
+  --profiles-file <profiles.yaml> --profile q-squeeze \
+  --size-pattern 6x200B+1x28KB --rate-hz 31 --duration 45 --repeats 1 \
+  --bin-s 1 --no-plot
+```
+
+| condition | ramp | delay across it | offered | lost in ramp | whole run |
+|---|---:|---|---:|---:|---:|
+| `q-clean` | none | 29.9 ms flat | — | — | 0 / 1398 = 0.00 % |
+| `q-loss` | none | 29.2 ms flat | — | — | 35 / 1397 = 2.51 % |
+| `q-squeeze` | 18 bins | 532 → 5623 ms | 558 | **0** | 84 / 1317 = 6.38 % |
+| `q-squeeze-loss` | 18 bins | 538 → 5490 ms | 558 | **15 = 2.7 %** | 119 / 1314 = 9.06 % |
+
+The ramp is cut by the delay's own slope and never by its loss — a bin belongs
+to it when the median delay gained at least 250 ms over the bin before it. The
+shaped bins gain about 295 ms each; the first bin to lose gains 221 and falls
+outside by that rule rather than by its outcome. Without that discipline the
+measurement defines its own answer.
+
+Three readings:
+
+1. **Queueing is not a loss process.** Eighteen bins, 558 messages, zero. At the
+   0.6 % per-packet rate the same load carries in `q-loss`, 558 messages of mean
+   4.2 fragments would carry ~14 losses; the shaped-but-clean arm has none,
+   because there is nothing to lose them to.
+2. **Queueing does not amplify the link's loss either.** `q-squeeze-loss` loses
+   2.7 % during a ramp whose delay reaches 5.5 s, against 2.51 % on the same link
+   with no queue at all. The queue defers packets; it does not damage them.
+3. **What ends it is the buffer, and it ends abruptly.** 97 % of a single bin,
+   not a gradual rise. The lossless window is therefore bounded by buffer depth
+   over excess rate and can be computed in advance, which is the only part of
+   this a deployment can design against.
+
+Verification: manual, needs Docker and about three minutes per condition. Run
+the command above for each profile and read `time-bins.jsonl` beside
+`result.json`: the `q-squeeze` bins under the cap must show monotonically
+climbing `latency_p50_ms` with `lost = 0`, and `q-squeeze-loss` must show the
+same climb with `lost` at the unshaped arm's rate.
+
+## Status
+
+confirmed, 2026-09-01.
+
+## Publication notes
+
+This is the control the field could not supply. On a real cellular uplink the
+two signals never separate — in the KAMO August campaign, thirty-six
+pre-registered filling episodes over 168 s (delay rising for three or more
+consecutive seconds, gaining at least 150 ms) lose 2.34 % against the 2.27 %
+their own seconds' rate predicts, P(at most this many) = 0.71 — because whatever reduces
+the grant also raises the error rate. Reading that field result alone, one would
+conclude a filling queue loses. This finding shows it does not: the loss belongs
+to the link and arrives whether or not the queue is filling.
+
+A two-host repeat over the FZI LAN (lamborghini orchestrating, seat as peer b
+through `remote-ota`) reached the peer, docker, and the containerized shaping
+capability on both sides and then stopped: `--peer-exec` requires
+`--install-mode checkout`, and checkout mode needs the project config inside the
+peer's own checkout, while the only OTA project registered on seat is
+`remote-assist`, whose session set has no synthetic benchmark session. So the
+LAN arm needs either a bench session in `remote-assist` or the harness on a
+second machine, and the four conditions above are single-host. That is the
+weaker setting for network realism and the stronger one for this question: on
+one host the shaper is the only thing between the peers, so a lossless ramp
+cannot be a property of some intervening link.
+
+It supersedes the reading in
+[oversubscription-queues-not-losses.md](oversubscription-queues-not-losses.md),
+which reported the same lossless ramp but attributed the boundary losses to the
+timeline step destroying the queue. Here the buffer overflows *inside* an
+unchanged shaping step, so the overflow is the queue's own limit rather than an
+artefact of `tc qdisc replace`.
+
+For papers: the pair `q-squeeze` / `q-squeeze-loss` is the figure. One ramp, one
+loss axis, two arms — it shows in a single panel that the delay is the queue's
+and the loss is the link's.

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/src/rosotacom/cli.py

@@ -3562,6 +3562,35 @@ def _ota_remote_package_dir(peer: OtaSmokePeer, plan: OtaSmokePlan, *, dry_run:
     return located
 
 
+def _ota_missing_project_message(plan: OtaSmokePlan, peer: OtaSmokePeer) -> str:
+    """Why one peer has no project file, in the terms that make it fixable.
+
+    `test -f` failing is the single most common way a checkout-mode run stops,
+    and the bare "exit code 1" it used to raise says nothing about the contract
+    it broke. The path is not resolved per peer: `--project` is split once, on
+    the orchestrator, into (checkout root, path inside it), and that *relative*
+    path is then asserted inside every peer's own `--peer-checkout`. So the
+    peers do not merely need a rosotacom project each — they need the same
+    repository, with the project at the same place in it.
+
+    The failure therefore has two ordinary causes and they want opposite fixes:
+    the peer is behind (sync it), or the project lives in a repository this peer
+    does not have (move the project, or point the peer at the repository that
+    holds it). Naming both is the difference between a minute and an afternoon.
+    """
+    workdir = _ota_peer_workdir(plan, peer)
+    return (
+        f"{peer.name}: {workdir}/{plan.project} does not exist.\n"
+        f"  --install-mode checkout resolves the project once, on this machine, into a checkout root and "
+        f"the path {plan.project!r} inside it, and then asserts that same relative path inside every peer's "
+        f"--peer-checkout. Every peer therefore needs the same repository, with the project at the same "
+        f"place in it -- not a project of its own.\n"
+        f"  If {peer.name} has that repository, it is behind: sync it and run again.\n"
+        f"  If it does not, the project is in the wrong repository for this run. Move it into the one the "
+        f"peers actually have, or give this peer --peer-checkout for a checkout that holds it."
+    )
+
+
 def _ota_verify_checkouts(plan: OtaSmokePlan, *, dry_run: bool) -> None:
     """Checkout mode's replacement for staging: assert, do not install.
 
@@ -3583,13 +3612,16 @@ def _ota_verify_checkouts(plan: OtaSmokePlan, *, dry_run: bool) -> None:
             dry_run=dry_run,
             batch=True,
         )
-        _ota_run(
+        found = _ota_run(
             peer,
             f"test -f {checkout}/{project}",
             label=f"{peer.name}: project config {plan.project} inside the checkout",
             dry_run=dry_run,
+            check=False,
             batch=True,
         )
+        if found.returncode != 0:
+            raise RuntimeError(_ota_missing_project_message(plan, peer))
         _ota_run(
             peer,
             f"{OTA_CHECKOUT_PATH_PREFIX}command -v rosotacom >/dev/null 2>&1",

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/src/rosotacom_dev.egg-info/PKG-INFO

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

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/src/rosotacom_dev.egg-info/SOURCES.txt

@@ -78,6 +78,7 @@ docs/findings/lighter-message-loss.md
 docs/findings/neither-a-queue-nor-a-burst-tilts-the-size-law.md
 docs/findings/one-domain-two-cyclone-configs-stop-interoperating.md
 docs/findings/oversubscription-queues-not-losses.md
+docs/findings/queueing-adds-delay-not-loss.md
 docs/findings/reorder-becomes-reader-loss.md
 docs/findings/sender-rows-make-a-dead-link-look-loss-free.md
 docs/findings/the-size-law-belongs-to-the-transport-not-the-link.md

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/src/rosotacom_dev.egg-info/scm_file_list.json

@@ -62,6 +62,7 @@
     "docs/findings/neither-a-queue-nor-a-burst-tilts-the-size-law.md",
     "docs/findings/one-domain-two-cyclone-configs-stop-interoperating.md",
     "docs/findings/oversubscription-queues-not-losses.md",
+    "docs/findings/queueing-adds-delay-not-loss.md",
     "docs/findings/reorder-becomes-reader-loss.md",
     "docs/findings/repro/decode_chain_repro.py",
     "docs/findings/repro/reorder_drop_repro.py",

rosotacom_dev-2.5.dev82/src/rosotacom_dev.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.4",
+  "distance": 82,
+  "node": "g0bd86d806f93ae00ec7f7009dd35fe5a018852e8",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-09-01"
+}

{rosotacom_dev-2.5.dev80 → rosotacom_dev-2.5.dev82}/tests/unit/test_cli.py

@@ -3506,6 +3506,32 @@ def test_ota_checkout_mode_runs_each_peer_from_its_own_checkout(tmp_path: Path)
     assert "--rosotacom-config session/rosotacom.yaml" in command
 
 
+def test_ota_checkout_mode_names_the_shared_repository_when_a_peer_lacks_the_project(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # The path is split once here and asserted on every peer, so a peer whose
+    # checkout is a *different* repository fails this probe -- and used to fail
+    # it as a bare "exit code 1", which reads as a broken machine rather than as
+    # the contract it is. Two runs were spent on that in one afternoon: a bench
+    # driven from the harness checkout, with a peer that only has the fleet
+    # repository, cannot resolve one relative path on both sides.
+    plan = _ota_checkout_plan(_write_checkout_project(tmp_path))
+
+    def fake_run(peer, script, *, label, **kwargs):
+        code = 1 if script.startswith("test -f") and peer.name == "b" else 0
+        return subprocess.CompletedProcess([], code, "", "")
+
+    monkeypatch.setattr(rosotacom, "_ota_run", fake_run)
+
+    with pytest.raises(RuntimeError) as error:
+        rosotacom._ota_verify_checkouts(plan, dry_run=False)
+
+    message = str(error.value)
+    assert "/home/other/fleet_mgmt/session/rosotacom.yaml does not exist" in message
+    assert "the same repository" in message
+    assert "it is behind: sync it" in message
+
+
 def test_ota_checkout_mode_puts_pipx_on_path_because_ssh_is_not_a_login_shell(tmp_path: Path) -> None:
     # `ssh host 'cmd'` skips the login profile, so a pipx install in
     # ~/.local/bin is invisible and the peer answers "command not found" —

rosotacom_dev-2.5.dev80/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.4",
-  "distance": 80,
-  "node": "g20983ff6a2471626fc5c940a3cfbf8e87a92b1cd",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-31"
-}