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

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

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

{rosotacom_dev-2.5.dev42 → 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.dev42 → 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.dev42 → 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.dev42 → 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.dev42 → rosotacom_dev-2.5.dev47}/src/rosotacom/forensics.py

@@ -42,6 +42,11 @@ RATE_COLLAPSE = "rate_collapse"
 KEYFRAME_SHARE_MIN = 0.02
 KEYFRAME_SHARE_MAX = 0.4
 
+# Real per-message FFMPEG flags win over the size heuristic once they cover
+# most delivered rows; the slack tolerates isolated parse failures in a
+# recording that otherwise carries the field.
+KEYFRAME_FLAG_COVERAGE_MIN = 0.9
+
 CAVEAT = (
     "Context is correlation, not causation: a link-trace sample or profile step that overlaps an event "
     "does not prove it caused the event. The causal test is reproduction under an emulated profile."
@@ -228,13 +233,27 @@ class Stream:
 
 
 def _annotate_keyframes(stream: Stream, *, declared: bool) -> None:
-    """Mark keyframes by size bimodality (transit records carry sizes, not FFMPEG flags).
-
-    ``rosotacom.ffmpeg_packet.keyframes_by_size`` is the documented fallback for
-    exactly this case. Declared FFMPEGPacket streams (type from status.json) are
-    always annotated; other streams only when the flagged share looks like a real
-    GOP structure, so uniform or spiky non-video streams are not mislabeled.
+    """Mark keyframes, preferring the real FFMPEG flags in the transit records.
+
+    The receiver parses ``AV_PKT_FLAG_KEY`` out of the wrapped FFMPEGPacket CDR
+    at com_in and writes it as ``keyframe`` on delivered rows, so when the field
+    covers (nearly) all delivered rows the real flags are authoritative — the
+    field only exists where the wrapper's ``msg_type`` named an FFMPEGPacket,
+    which is a stronger declaration than status.json, so no share gate applies.
+
+    Recordings from before the field existed fall back to
+    ``rosotacom.ffmpeg_packet.keyframes_by_size``: declared FFMPEGPacket streams
+    (type from status.json) are always annotated; other streams only when the
+    flagged share looks like a real GOP structure, so uniform or spiky
+    non-video streams are not mislabeled.
     """
+    delivered = [record for record in stream.records if record.get("status") != "lost"]
+    flagged = [record for record in delivered if isinstance(record.get("keyframe"), bool)]
+    if delivered and len(flagged) / len(delivered) > KEYFRAME_FLAG_COVERAGE_MIN:
+        stream.keyframe_seqs = frozenset(int(record["seq"]) for record in flagged if record["keyframe"])
+        stream.keyframe_provenance = "ffmpeg_flags (transit records)"
+        return
+
     sized = [record for record in stream.records if record.get("size_bytes") is not None]
     if not sized:
         return
@@ -246,7 +265,7 @@ def _annotate_keyframes(stream: Stream, *, declared: bool) -> None:
         return
     stream.keyframe_seqs = frozenset(int(record["seq"]) for record, flag in zip(sized, flags, strict=True) if flag)
     origin = "declared FFMPEGPacket stream" if declared else f"size share {share * 100.0:.1f}%"
-    stream.keyframe_provenance = f"size_bimodality ({origin}); transit records carry no FFMPEG flags"
+    stream.keyframe_provenance = f"size_bimodality ({origin}); these transit records carry no FFMPEG flags"
 
 
 def build_streams(records: list[dict[str, Any]], *, declared_ffmpeg_topics: Collection[str] = ()) -> list[Stream]:
@@ -342,6 +361,52 @@ def build_stream_bins(stream: Stream, *, run_start: float, bin_s: float) -> list
     return bins
 
 
+def build_offered_timelines(
+    offered_records: list[dict[str, Any]],
+    streams: list[Stream],
+    timelines: dict[str, list[dict[str, Any]]],
+    *,
+    run_start: float,
+    bin_s: float,
+) -> dict[str, list[float]]:
+    """Per-bin offered rate per stream, from the sending peer's own transit records.
+
+    ``offered_records`` are ``direction: outbound`` rows (stage ``com_out``):
+    what the source handed to the link. Their ``t_wrap`` is the same header
+    stamp the receiving side records, so offered and delivered bins share one
+    publish timeline with no clock join. Streams without a single stamped
+    sender-side row are absent from the result — their collapse cause stays
+    unknowable.
+    """
+    grouped: dict[tuple[str, str, str], list[float]] = {}
+    for record in join_transit_records(offered_records):
+        if record.get("t_wrap") is None:
+            continue
+        key = (
+            str(record.get("source") or ""),
+            str(record.get("target") or ""),
+            str(record.get("topic") or ""),
+        )
+        grouped.setdefault(key, []).append(float(record["t_wrap"]))
+
+    offered: dict[str, list[float]] = {}
+    for stream in streams:
+        stamps = grouped.get((stream.source, stream.target, stream.topic))
+        bins = timelines[stream.label]
+        if not stamps or not bins:
+            continue
+        # bin_start_epoch is run_start + index * bin_s by construction; round
+        # instead of floor so float error cannot shift the alignment by one.
+        first_index = round((float(bins[0]["bin_start_epoch"]) - run_start) / bin_s)
+        counts = [0] * len(bins)
+        for stamp in stamps:
+            index = math.floor((stamp - run_start) / bin_s) - first_index
+            if 0 <= index < len(counts):
+                counts[index] += 1
+        offered[stream.label] = [round(count / bin_s, 3) for count in counts]
+    return offered
+
+
 # --------------------------------------------------------------------------- #
 # Event detection
 # --------------------------------------------------------------------------- #
@@ -470,7 +535,11 @@ def detect_latency_excursions(stream: Stream, config: DetectionConfig) -> list[D
 
 
 def detect_rate_collapses(
-    stream: Stream, bins: list[dict[str, Any]], config: DetectionConfig
+    stream: Stream,
+    bins: list[dict[str, Any]],
+    config: DetectionConfig,
+    *,
+    offered_hz: list[float] | None = None,
 ) -> list[DegradationEvent]:
     """Runs of >= ``rate_collapse_min_bins`` interior bins delivering far below nominal.
 
@@ -478,45 +547,75 @@ def detect_rate_collapses(
     becomes lost rows when a later message arrives) and throttled-but-delivering
     regimes. Needs a nominal rate; the first and last bin of a stream are never
     judged (they are partial by construction).
+
+    ``offered_hz`` — one rate per entry of ``bins``, from the sending peer's own
+    records (``build_offered_timelines``) — names each event's culprit as
+    ``cause``: ``source`` when every collapsed bin was offered below the same
+    threshold (the collapse is fully explained by the source pausing or slowing;
+    the link delivered what it was given), ``link`` when at least one collapsed
+    bin was offered at/above threshold and the link still delivered below it,
+    and ``unknown`` without sender-side records. The receiver alone cannot tell
+    these apart: on the 2026-08-17 CCNG drive, 0 Hz "collapses" on the planner
+    visualization were the source pausing during manual interventions, not the
+    link.
     """
     nominal_hz = stream.nominal_hz
     if nominal_hz is None or len(bins) < 3:
         return []
+    threshold_hz = config.rate_collapse_fraction * nominal_hz
     events: list[DegradationEvent] = []
-    run: list[dict[str, Any]] = []
+    run: list[tuple[int, dict[str, Any]]] = []
+
+    def cause_details() -> dict[str, Any]:
+        if offered_hz is None or len(offered_hz) != len(bins):
+            return {"cause": "unknown"}
+        rates = [float(offered_hz[index]) for index, _entry in run]
+        return {
+            "cause": "source" if max(rates) < threshold_hz else "link",
+            "min_offered_hz": round(min(rates), 3),
+            "max_offered_hz": round(max(rates), 3),
+        }
 
     def flush() -> None:
         if len(run) >= config.rate_collapse_min_bins:
+            entries = [entry for _index, entry in run]
             events.append(
                 DegradationEvent(
                     kind=RATE_COLLAPSE,
                     stream=stream.label,
-                    start_epoch=float(run[0]["bin_start_epoch"]),
-                    end_epoch=float(run[-1]["bin_start_epoch"]) + config.bin_s,
-                    count=len(run),
+                    start_epoch=float(entries[0]["bin_start_epoch"]),
+                    end_epoch=float(entries[-1]["bin_start_epoch"]) + config.bin_s,
+                    count=len(entries),
                     details={
                         "nominal_hz": round(nominal_hz, 3),
-                        "min_delivered_hz": min(float(entry["delivered_hz"]) for entry in run),
-                        "threshold_hz": round(config.rate_collapse_fraction * nominal_hz, 3),
+                        "min_delivered_hz": min(float(entry["delivered_hz"]) for entry in entries),
+                        "threshold_hz": round(threshold_hz, 3),
+                        **cause_details(),
                     },
                 )
             )
         run.clear()
 
-    for entry in bins[1:-1]:
-        if float(entry["delivered_hz"]) < config.rate_collapse_fraction * nominal_hz:
-            run.append(entry)
+    for index, entry in enumerate(bins[1:-1], start=1):
+        if float(entry["delivered_hz"]) < threshold_hz:
+            run.append((index, entry))
         else:
             flush()
     flush()
     return events
 
 
-def detect_events(stream: Stream, bins: list[dict[str, Any]], config: DetectionConfig) -> list[DegradationEvent]:
+def detect_events(
+    stream: Stream,
+    bins: list[dict[str, Any]],
+    config: DetectionConfig,
+    *,
+    offered_hz: list[float] | None = None,
+) -> list[DegradationEvent]:
     events = [
         *detect_loss_bursts(stream, config),
         *detect_latency_excursions(stream, config),
-        *detect_rate_collapses(stream, bins, config),
+        *detect_rate_collapses(stream, bins, config, offered_hz=offered_hz),
     ]
     events.sort(key=lambda event: (event.start_epoch, event.end_epoch, event.kind, event.stream))
     return events
@@ -843,8 +942,15 @@ def build_report(
     config = config or DetectionConfig()
     inputs = discover_inputs(instance_dir, peers=peers)
     records = load_transit_records(inputs.events_paths)
+    # The sending peer's own rows (direction=outbound, stage com_out) carry the
+    # offered rate. They must stay out of the delivered view: the cross-peer
+    # join keys on (source, topic, epoch, seq), so a sender row would upgrade
+    # the receiver's lost row to delivered and flatten delivered_hz to the
+    # offered rate.
+    offered_records = [record for record in records if record.get("direction") == "outbound"]
+    delivered_records = [record for record in records if record.get("direction") != "outbound"]
     declared = load_declared_ffmpeg_topics(inputs.status_paths)
-    streams = build_streams(records, declared_ffmpeg_topics=declared)
+    streams = build_streams(delivered_records, declared_ffmpeg_topics=declared)
 
     send_spans = [(stream.send_time(stream.records[0]), stream.send_time(stream.records[-1])) for stream in streams]
     run_start = min((span[0] for span in send_spans), default=0.0)
@@ -859,9 +965,10 @@ def build_report(
     )
 
     timelines = {stream.label: build_stream_bins(stream, run_start=run_start, bin_s=config.bin_s) for stream in streams}
+    offered = build_offered_timelines(offered_records, streams, timelines, run_start=run_start, bin_s=config.bin_s)
     events: list[DegradationEvent] = []
     for stream in streams:
-        events.extend(detect_events(stream, timelines[stream.label], config))
+        events.extend(detect_events(stream, timelines[stream.label], config, offered_hz=offered.get(stream.label)))
     events.sort(key=lambda event: (event.start_epoch, event.end_epoch, event.kind, event.stream))
 
     incidents = group_incidents(events, merge_gap_s=config.merge_gap_s)
@@ -881,7 +988,7 @@ def build_report(
 
     from .transit import summarize_transit_records
 
-    summary = summarize_transit_records(records)["topics"]
+    summary = summarize_transit_records(delivered_records)["topics"]
     stream_entries: dict[str, Any] = {}
     for stream in streams:
         entry = dict(summary.get(stream.label, {}))
@@ -984,9 +1091,21 @@ def _event_line(event: dict[str, Any]) -> str:
             f"baseline {_format_ms(details.get('baseline_ms'))} (threshold {_format_ms(details.get('threshold_ms'))}), "
             f"{window}"
         )
+    cause = details.get("cause")
+    if cause == "source":
+        name = (
+            "rate collapse (source paused)" if details.get("max_offered_hz") == 0.0 else "rate collapse (source slowed)"
+        )
+    elif cause == "link":
+        name = "rate collapse (link)"
+    else:
+        name = "rate collapse"
+    low, high = details.get("min_offered_hz"), details.get("max_offered_hz")
+    offered = "" if low is None else (f", offered {low}Hz" if low == high else f", offered {low}-{high}Hz")
+    suffix = "" if cause in ("source", "link") else "; cause unknown (no sender-side records)"
     return (
-        f"**rate collapse** on `{event['stream']}` — {event['count']} bins, delivered rate down to "
-        f"{details.get('min_delivered_hz')}Hz vs nominal {details.get('nominal_hz')}Hz, {window}"
+        f"**{name}** on `{event['stream']}` — {event['count']} bins, delivered rate down to "
+        f"{details.get('min_delivered_hz')}Hz vs nominal {details.get('nominal_hz')}Hz{offered}, {window}{suffix}"
     )