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

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

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

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev47}/docs/ffmpeg-keyframes.md

@@ -45,6 +45,18 @@ Grouping a stream into GOPs is then just splitting at keyframes. Note the
 encoder may emit keyframes *early* (scene cuts), so GOPs can be shorter than
 `gop_size` — assert spacing `<= gop_size`, not `== gop_size`.
 
+## Transit records carry the flag
+
+The receiving status overview applies the same parse live: when an inbound
+`OtaStamped` envelope's `msg_type` names an FFMPEGPacket, it walks the wrapped
+CDR bytes to `flags` (`com_py/ffmpeg_flags.py`, a dependency-free mirror of the
+host parser) and writes `keyframe: true/false` on every delivered RFC 0003
+transit row in `events.jsonl`. Synthesized lost rows have no payload and carry
+no such field; a payload the walk cannot parse simply omits it. Downstream,
+`rosotacom report` annotates a stream from these real flags whenever they cover
+more than 90% of its delivered rows (provenance `ffmpeg_flags (transit
+records)`), and only recordings without the field fall back to size bimodality.
+
 ## Automated stream-stage stats
 
 `rosotacom stream-stats` applies the same packet parser and GOP grouping to
@@ -69,8 +81,9 @@ Inputs are explicit and repeatable:
   rosbag2 storage backends fall back to `rosbag2_py` in a ROS environment.
 - `--events LABEL=PATH:/topic` reads delivered RFC 0003 transit rows from
   `events.jsonl`, using receiver-side `t_com_in` timestamps and `size_bytes`.
-  Transit rows do not carry raw CDR flags, so GOP annotation uses the documented
-  size-bimodality fallback when the keyframe share looks like a real GOP.
+  Rows carrying the per-message `keyframe` field annotate GOPs from the real
+  flags; older recordings without it use the documented size-bimodality
+  fallback when the keyframe share looks like a real GOP.
 
 The Markdown output starts with the comparison table:
 
@@ -105,9 +118,9 @@ averages 43,723 B, while positions 1-4 average 3,738 B, 4,512 B, 4,834 B, and
 
 ## Fallback: size bimodality
 
-If `flags` is unavailable (foreign recordings, or bags anonymized before
-flag preservation existed), the size distribution still separates the two
-classes: delta frames dominate the stream (a GOP of N contributes N−1), so
+If `flags` is unavailable (foreign recordings, bags anonymized before flag
+preservation existed, or `events.jsonl` written before transit rows carried
+`keyframe`), the size distribution still separates the two classes: delta frames dominate the stream (a GOP of N contributes N−1), so
 the median frame size sits on the delta mode, while keyframes are typically
 5–100× larger. `rosotacom.ffmpeg_packet.keyframes_by_size` marks frames
 above `3 × median` as keyframes. This misclassifies only when delta frames
@@ -119,6 +132,12 @@ scene at a very low bitrate) — prefer `flags` whenever present.
 - `tests/unit/test_ffmpeg_packet.py` — CDR parsing (alignment across
   odd-length strings), flag semantics, and the size fallback on a synthetic
   GOP pattern.
+- `tests/unit/test_ffmpeg_flags.py` — the receiver-side keyframe-bit walk in
+  `com_py/ffmpeg_flags.py`: agreement with the host parser on hand-built
+  packets, and `None` (never an exception) on truncated or foreign bytes.
+- `tests/unit/test_forensics.py` — `rosotacom report` prefers transit-row
+  `keyframe` flags over size bimodality, and falls back below the coverage
+  gate.
 - `tests/unit/test_stream_stats.py` — exact stream statistics, per-GOP-position
   tables from hand-built CDR packets, events-row source loading, comparison
   table shape, and CLI output writing.

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev47}/docs/findings/README.md

@@ -28,6 +28,7 @@ living verification hook.
 
 ## Findings
 
+- [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.
 - [Lighter alternating messages can lose more than steady messages](lighter-message-loss.md) - a 1x18KB+1x0KB pattern lost under a tight emulated profile while the steady 18 KB comparison did not.
 - [Delay alone was not the loss boundary for the 18 KB at 20 Hz probe](delay-alone-no-loss.md) - pure delay profiles showed no material loss, and the 300 ms delay-only probe delivered all messages.

rosotacom_dev-2.5.dev47/docs/findings/reorder-becomes-reader-loss.md

@@ -0,0 +1,69 @@
+# Best-Effort Reordering Becomes Reader-Side Loss, Independent Of History Depth
+
+## Claim
+
+Under delay jitter large enough to reorder packets — with ZERO configured
+loss — a CycloneDDS best-effort reader discards every overtaken sample to
+preserve per-writer order: delivery is strictly monotonic, the discarded
+samples count as loss, and subscription history depth does not recover any of
+it (the drop happens in the reader proxy, before history). Variance is
+therefore a loss mechanism of its own, and it is the one QoS depth cannot
+help against — unlike bundled-publication overwrite, where depth does help.
+
+## Setup
+
+- Host pair / topology: two Docker containers on one machine (the repository's
+  communication image; any image with `rclpy`, `rmw_cyclonedds_cpp` and `tc`
+  works), unicast Cyclone peers (`AllowMulticast=false`, static IPs), one
+  `std_msgs/Int64` stream at 100 Hz, publisher history depth 10, best-effort;
+  the receiver subscribes the SAME topic twice: depth 1 and depth 50. netem on
+  the publisher's egress only, delay+jitter, no loss, no rate limit.
+- rosotacom SHA: measured at `3227daf`; re-runs record theirs.
+- Profile: inline netem args (`delay 50ms 45ms` and `delay 50ms 20ms`), not a
+  packaged profile — the experiment is below rosotacom, at the RMW layer.
+- Seed policy: seedless single runs (`n=1` per jitter level); the effect size
+  (tens of percent) dwarfs run-to-run noise.
+
+## Evidence
+
+Evidence grade: scripted container reproduction, committed next to this file.
+
+```bash
+python3 docs/findings/repro/reorder_drop_repro.py orchestrate --rate 100 --duration 40
+```
+
+2026-08-18 run (4000 messages sent per scenario, zero configured loss):
+
+| netem | depth 1 delivered | depth 50 delivered | inversions | loss of span |
+|---|---|---|---|---|
+| `delay 50ms 45ms` | 1709 | 1727 | 0 | **57%** |
+| `delay 50ms 20ms` | 2626 | 2659 | 0 | **34%** |
+
+Three readings, one per column group: delivery is strictly monotonic (zero
+inversions in every subscription), depth 50 loses the same as depth 1 (the
+0.5–1 pp difference is executor noise, not recovery), and the loss tracks the
+overtake probability — at 100 Hz the inter-message gap is 10 ms, so jitter
+±45 ms makes "the next message arrives first" the common case.
+
+Field context (2026-08-17 CCNG drive): the operational 10 Hz streams have a
+100 ms gap against ~18 ms steady jitter, so this channel is minor there
+(neighbour-delay overtake proxy: 9.6% around steady losses vs 6.0% baseline).
+It grows quadratically relevant as rates rise or jitter grows — any stream
+whose inter-message gap approaches the link's jitter pays it.
+
+Verification: manual: run the command above from a source checkout with
+Docker (build the image via the packaged `ros2docker.json.example` or pass
+`--image`); the script prints and writes `out/reorder_results.json`.
+
+## Status
+
+confirmed, 2026-08-18.
+
+## Publication notes
+
+This is the mechanism behind the jitter side of
+[jitter-loss-bandwidth-latency.md](jitter-loss-bandwidth-latency.md): the
+jitter boundary is not radio noise but the reader's monotonicity rule. For
+papers: plot delivered share vs jitter/gap ratio, and state explicitly that
+history depth is not a mitigation here — pacing (larger gaps), FEC, or
+reliable QoS are.

rosotacom_dev-2.5.dev47/docs/findings/repro/reorder_drop_repro.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Does jitter-induced reordering become LOSS at a CycloneDDS best-effort
+reader, and does history depth help?
+
+Two containers (rcd image, cyclone RMW). Publisher shapes its egress with
+pure delay+jitter (NO configured loss, no rate limit). Receiver subscribes
+the same topic twice: depth 1 and depth 50.
+
+Discriminates two mechanisms:
+  - loss seen by depth-50 sub  = reader-proxy drop of overtaken samples
+    (depth cannot help)        (or nothing, if cyclone delivers OOO)
+  - extra loss of depth-1 sub  = history overwrite from arrival bunching
+    (depth DOES help)
+  - delivered inversions       = out-of-order delivery (would mean no drop)
+
+Modes: orchestrate (host) | pub | sub (in container).
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+IMG = "ros-communication:latest"  # any image with rclpy + rmw_cyclonedds + tc (--image overrides)
+NET = "claude_reorder_net"
+TOPIC = "/reorder_probe"
+
+
+def mode_pub(args):
+    import rclpy
+    from rclpy.node import Node
+    from rclpy.qos import HistoryPolicy, QoSProfile, ReliabilityPolicy
+    from std_msgs.msg import Int64
+
+    rclpy.init()
+    node = Node("reorder_pub")
+    qos = QoSProfile(reliability=ReliabilityPolicy.BEST_EFFORT, history=HistoryPolicy.KEEP_LAST, depth=10)
+    pub = node.create_publisher(Int64, TOPIC, qos)
+    time.sleep(5.0)  # discovery
+    n = int(args.rate * args.duration)
+    period = 1.0 / args.rate
+    t0 = time.monotonic()
+    for i in range(n):
+        while time.monotonic() < t0 + i * period:
+            time.sleep(0.0005)
+        m = Int64()
+        m.data = i
+        pub.publish(m)
+    time.sleep(3.0)
+    print(f"published {n}")
+    node.destroy_node()
+    rclpy.shutdown()
+
+
+def mode_sub(args):
+    import rclpy
+    from rclpy.node import Node
+    from rclpy.qos import HistoryPolicy, QoSProfile, ReliabilityPolicy
+    from std_msgs.msg import Int64
+
+    rclpy.init()
+    node = Node("reorder_sub")
+    got = {1: [], 50: []}
+
+    def make_cb(depth):
+        def cb(msg):
+            got[depth].append(msg.data)
+
+        return cb
+
+    subs = []
+    for depth in (1, 50):
+        qos = QoSProfile(reliability=ReliabilityPolicy.BEST_EFFORT, history=HistoryPolicy.KEEP_LAST, depth=depth)
+        subs.append(node.create_subscription(Int64, TOPIC, make_cb(depth), qos))
+    t_end = time.monotonic() + args.duration + 20
+    while time.monotonic() < t_end:
+        rclpy.spin_once(node, timeout_sec=0.05)
+    out = {}
+    for depth, seqs in got.items():
+        inv = sum(1 for a, b in zip(seqs, seqs[1:], strict=False) if b < a)
+        out[f"depth{depth}"] = {
+            "received": len(seqs),
+            "unique": len(set(seqs)),
+            "inversions": inv,
+            "first": seqs[0] if seqs else None,
+            "last": max(seqs) if seqs else None,
+        }
+    Path(args.out).write_text(json.dumps(out, indent=2))
+    print(json.dumps(out))
+    node.destroy_node()
+    rclpy.shutdown()
+
+
+def run(cmd):
+    r = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+    if r.returncode != 0:
+        raise RuntimeError(f"{cmd}\n{r.stderr or r.stdout}")
+    return r.stdout
+
+
+def mode_orchestrate(args):
+    global IMG
+    IMG = args.image
+    me = Path(__file__).resolve()
+    outdir = me.parent / "out"
+    scenarios = [
+        ("jitter45", "tc qdisc replace dev eth0 root netem delay 50ms 45ms"),
+        ("jitter20", "tc qdisc replace dev eth0 root netem delay 50ms 20ms"),
+    ]
+    ip_sub, ip_pub = "10.97.0.2", "10.97.0.3"
+    ddsuri = (
+        "<CycloneDDS><Domain><General><AllowMulticast>false</AllowMulticast>"
+        '</General><Discovery><Peers><Peer address=\\"' + ip_sub + '\\"/>'
+        '<Peer address=\\"' + ip_pub + '\\"/></Peers>'
+        "<ParticipantIndex>auto</ParticipantIndex></Discovery></Domain></CycloneDDS>"
+    )
+    subprocess.run(f"docker network rm {NET}", shell=True, capture_output=True)
+    run(f"docker network create --subnet 10.97.0.0/24 {NET}")
+    results = {}
+    try:
+        for name, netem in scenarios:
+            subprocess.run("docker rm -f claude_reorder_pub claude_reorder_sub", shell=True, capture_output=True)
+            env = f'-e RMW_IMPLEMENTATION=rmw_cyclonedds_cpp -e ROS_DOMAIN_ID=77 -e CYCLONEDDS_URI="{ddsuri}"'
+            run(
+                f"docker run -d --name claude_reorder_sub --network {NET} --ip {ip_sub} {env} "
+                f"-v {me.parent}:/w -v {outdir}:/out {IMG} bash -lc "
+                f"'python3 /w/{me.name} sub --duration {args.duration} "
+                f"--out /out/reorder_{name}.json'"
+            )
+            time.sleep(2)
+            run(
+                f"docker run -d --name claude_reorder_pub --network {NET} --ip {ip_pub} "
+                f"--cap-add NET_ADMIN {env} -v {me.parent}:/w {IMG} bash -lc "
+                f"'{netem} && python3 /w/{me.name} pub --rate {args.rate} "
+                f"--duration {args.duration}'"
+            )
+            run("docker wait claude_reorder_pub")
+            run("docker wait claude_reorder_sub")
+            data = json.loads((outdir / f"reorder_{name}.json").read_text())
+            sent = int(args.rate * args.duration)
+            for d in ("depth1", "depth50"):
+                span = (data[d]["last"] or 0) - (data[d]["first"] or 0) + 1
+                data[d]["loss_pct_of_span"] = round(100 * (1 - data[d]["unique"] / max(span, 1)), 2)
+            data["sent"] = sent
+            results[name] = data
+            print(f"== {name}: {json.dumps(data)}")
+    finally:
+        subprocess.run("docker rm -f claude_reorder_pub claude_reorder_sub", shell=True, capture_output=True)
+        subprocess.run(f"docker network rm {NET}", shell=True, capture_output=True)
+    (outdir / "reorder_results.json").write_text(json.dumps(results, indent=2))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="mode", required=True)
+    for m in ("orchestrate", "pub", "sub"):
+        p = sub.add_parser(m)
+        p.add_argument("--rate", type=float, default=100.0)
+        p.add_argument("--duration", type=float, default=40.0)
+        p.add_argument("--image", default=IMG)
+        if m == "sub":
+            p.add_argument("--out", required=True)
+    args = ap.parse_args()
+    {"pub": mode_pub, "sub": mode_sub, "orchestrate": mode_orchestrate}[args.mode](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

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

@@ -77,6 +77,22 @@ missing tail after the last record is not judged either — without a sender-sid
 end marker it is indistinguishable from a normal shutdown (RFC 0003, honest
 limits).
 
+A receiver-only view also cannot tell a broken link from a source that simply
+stopped publishing — on the 2026-08-17 CCNG drive, "0 Hz collapses" on the
+planner visualization were the source pausing during manual interventions while
+the link delivered everything offered. When the instance also contains the
+sending peer's own transit records for a stream (`direction: outbound`, stage
+`com_out`), the report bins their `t_wrap` stamps into a per-bin **offered**
+rate on the same publish timeline and each collapse event names its culprit in
+`details.cause`: `source` when every collapsed bin was offered below the same
+threshold — the collapse is fully explained by the source, and the markdown
+line reads "source paused" (0 Hz offered) or "source slowed"; `link` when at
+least one collapsed bin was offered at/above threshold and the link still
+delivered below it; `unknown` without sender-side records. `min_offered_hz` /
+`max_offered_hz` accompany the verdict. Sender-side rows feed only the offered
+rate — they never enter the delivered view, where the cross-peer join would
+upgrade receiver-inferred lost rows to delivered.
+
 Events across streams and kinds are grouped into **incidents** when their
 windows touch (merge gap defaults to one bin): one degradation moment, several
 lenses on it.

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev47}/docs/rfcs/0004-network-profiles.md

@@ -91,11 +91,24 @@ profiles:
       - { for: 40s, uplink: { rate: 2.5mbit, delay: 90ms,  loss: 1%   } }
 ```
 
-- **static** — constant `{rate, delay, jitter, distribution, loss,
-  loss_correlation, reorder, duplicate, seed}` per direction. `loss_correlation`
-  (netem state/`gemodel`) makes loss bursty rather than independent — closer to
-  real radio loss. `seed` maps to `tc netem seed SEED` when supported, making the
-  generated random delay/loss draw replayable.
+- **static** — constant `{rate, delay, jitter, distribution, distribution_file,
+  loss, loss_correlation, loss_gemodel, reorder, duplicate, seed}` per
+  direction. Two loss models, mutually exclusive per direction:
+  `loss` (+ optional `loss_correlation`) is netem's independent/correlated
+  per-packet loss; `loss_gemodel: {p, r, loss_bad, loss_good}` is the
+  Gilbert–Elliott state model (`tc netem loss gemodel`), the vocabulary a real
+  cellular link needs — rare transitions into a short intense bad state
+  (`p`/`r` per packet) with distinct loss probabilities inside (`loss_bad`)
+  and outside (`loss_good`) of it. The 2026-08-17 CCNG field fit is the
+  reference: `p 0.12%, r 2.9%, loss_bad 2.7%, loss_good 0.098%` reproduces
+  113 ms bad states every ~2.8 s. `distribution` accepts the iproute2
+  builtins (`normal|pareto|paretonormal`) or a custom table name whose
+  `distribution_file` (a `.dist` built by `python -m rosotacom.netem_dist`
+  from measured delay samples) the runner installs into the shaping netns as
+  `/usr/lib/tc/<name>.dist` — because a field link's delay is
+  lognormal-tailed and `normal` under-tails p99 by ~2x. `seed` maps to
+  `tc netem seed SEED` when supported, making the generated random
+  delay/loss draw replayable.
 - **timeline** — an ordered list of `{ for: <dur>, <static-params> | outage }`
   segments. A recovery benchmark (RFC 0005) *is* a timeline profile; `outage` is
   the step whose recovery is measured.
@@ -189,8 +202,11 @@ RFC 0002's `calibrate` / `--suggest` machinery, **per profile**:
   the fluctuation `netem` does not reproduce by default. Emulation buys
   **reproducibility, not truth** — rung 4 (real cellular) calibrates the
   *shape* of the emulated profile; the profile then gives repeatable gating.
-- **Bursty loss needs the state model.** Default `netem loss` is independent; use
-  `loss_correlation` / `gemodel` to approximate real burst loss.
+- **Bursty loss needs the state model.** Default `netem loss` is independent; the
+  2-arg `loss p% corr%` cannot express short-bad/long-good either. `loss_gemodel`
+  carries the Gilbert–Elliott parameters directly (see the schema section); fit
+  `p`/`r` from the measured bad/good run lengths (per packet) and the two loss
+  probabilities from the loss rate inside/outside bad states.
 - **Outage semantics are a choice.** `netem loss 100%` keeps the interface up (DDS
   endpoints survive, recovery is "catch up") vs link-down (forces RMW
   re-discovery, a harsher recovery). They test different recoveries — see Open
@@ -215,6 +231,12 @@ risk — a stuck `qdisc` silently corrupts every later result on the machine.
   `profiles.yaml` referenced from `rosotacom.yaml`), and resolve selection via
   `--profile <name>` / `shared.profile` / `none` (`resolve_profile_selection`,
   `cli._resolve_active_profile`).
+- [x] Extend the loss/delay vocabulary to what field links actually need
+  (issue #278): `loss_gemodel` (Gilbert–Elliott state loss, exclusive with
+  `loss`) and custom delay-distribution tables (`distribution` beyond the
+  builtins + `distribution_file`, generated from measured samples by
+  `rosotacom.netem_dist`, installed into the shaping netns by the lab runner
+  before arming).
 - [x] Arm a named static profile on the OTA-interface egress with fail-safe
   teardown (revert on stop, on error, and via a safety max-duration watchdog);
   target the data interface only, never the SSH/control interface
@@ -268,6 +290,21 @@ off during implementation). Notes whether automation is feasible; privileged
   for a given profile/direction (rate/delay/jitter/loss/correlation → `tbf`+`netem`
   string), without touching a real interface (`test_shaping_commands_*`,
   `test_netem_arg_ordering_is_valid`). Done.
+- [x] **Gilbert–Elliott loss (`loss_gemodel`)** — host unit tests on the schema
+  (required/unknown keys, exclusivity against `loss`) and on the argv (all four
+  probabilities always emitted): `test_gemodel_parse_and_exclusivity`,
+  `test_gemodel_argv_emits_all_four_probabilities`. The *statistical* fidelity of
+  the emitted process (bad-run length, in-state loss rates) stays a bench check
+  against a field fit — the 2026-08-17 CCNG fragment replay is the reference.
+- [x] **Custom delay-distribution tables** — host unit tests: a non-builtin
+  `distribution` requires `distribution_file` and resolves relative to the
+  profiles file (`test_custom_distribution_requires_a_file_and_builtin_does_not`,
+  `test_load_profiles_file_resolves_distribution_files_and_lists_installs`);
+  table generation is normalized, monotonic, tail-preserving
+  (`test_netem_dist.py`). The lab runner installs required tables into the
+  shaping netns before arming (`required_dist_installs` consumed in
+  `cli_benchmark`); that a netem referencing the installed name actually loads
+  it is part of the same bench check as arming itself.
 - [~] **Fail-safe teardown** (revert on stop, on error, on safety max-duration; the
   idempotent `tc qdisc del … root` always runs; data-interface-only, never the
   SSH/control interface) — host unit test on the teardown/targeting logic done

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev47}/session-configuration.md

@@ -568,6 +568,27 @@ number being reported.
 - `bit_rate` (int)
 - `encoder_av_options` (string)
 
+#### Receiver-side playout pacing (manual node)
+
+A receiver that hands every packet to the decoder the moment it arrives turns
+network delay jitter into display stutter. `com_py playout_pacer` re-times a
+received packet stream to `stamp + budget` (budget adaptive above the fastest
+observed path, clock-offset-proof; late packets pass through immediately, order
+always preserved — the decoder chain sees every packet):
+
+```bash
+ros2 run com_py playout_pacer --ros-args \
+  -p topic:=/cam/image/compressed/drop1of2/ffmpeg \
+  -p target_ms:=350.0 -p adaptive:=true
+```
+
+It republishes on `<topic>/paced` plus `.../paced/budget_ms` and
+`.../paced/queue_depth` debug topics; point the reverse republish (or any
+decoder) at the paced name. On the 2026-08-17 CCNG field trace this removes
+~95 % of delay-caused >200 ms display gaps at ~100 ms median added age
+(adaptive mode). Declarative wiring as a `transport.playout` block is tracked
+in issue #284.
+
 `type: foxglove` supports (CompressedVideo):
 - `gop_size` (int)
 - `bit_rate` (int)

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev47}/src/rosotacom/cli_benchmark.py

@@ -5514,6 +5514,30 @@ def _make_live_run_point(args: argparse.Namespace, session_name: str) -> RunPoin
 
                 # 3. Arm the network shapers (after discovery is complete)
                 if profile_obj is not None:
+                    from .network_profiles import required_dist_installs
+
+                    dist_installs = required_dist_installs(profile_obj)
+                    if dist_installs:
+                        # Custom delay-distribution tables must exist inside the
+                        # shaping netns before netem references them by name.
+                        for dist_container in (a_container, b_container):
+                            if not dist_container:
+                                continue
+                            for table_name, file_path in dist_installs:
+                                dist_target = f"/usr/lib/tc/{table_name}.dist"
+                                for install_cmd in (
+                                    ["docker", "exec", "-u", "root", dist_container, "mkdir", "-p", "/usr/lib/tc"],
+                                    ["docker", "cp", file_path, f"{dist_container}:{dist_target}"],
+                                ):
+                                    res = subprocess.run(install_cmd, capture_output=True, text=True, check=False)
+                                    if res.returncode != 0:
+                                        raise RuntimeError(
+                                            f"failed to install netem distribution table {table_name!r} in "
+                                            f"{dist_container}: {' '.join(install_cmd)} -> {res.stderr or res.stdout}"
+                                        )
+                                print(
+                                    f"  netem distribution {table_name!r} installed in {dist_container}: {dist_target}"
+                                )
                     if profile_obj.is_timeline:
                         # Peer A shapes uplink (egress to B)
                         shaper_a = ProfileShaper("eth0", make_container_runner(a_container))