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

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

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

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev42}/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.dev42}/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))

rosotacom_dev-2.5.dev42/src/rosotacom/netem_dist.py

@@ -0,0 +1,104 @@
+"""Build netem delay-distribution tables (``/usr/lib/tc/*.dist``) from samples.
+
+netem draws jitter as ``delay + jitter * table[uniform] / NETEM_DIST_SCALE``:
+the ``distribution`` argument names a table of signed 16-bit values that encode
+the *shape* (the inverse CDF of the normalized distribution, scaled by 8192),
+while ``delay``/``jitter`` supply location and scale. iproute2 ships only
+``normal``, ``pareto`` and ``paretonormal``; a field-measured delay
+distribution (e.g. the lognormal-tailed one-way delay of a cellular uplink,
+which ``normal`` badly under-tails) becomes reproducible by generating its own
+table from samples and installing it next to the builtin ones.
+
+This is the same construction as iproute2's ``maketable``: sort the samples,
+normalize to mean 0 / stddev 1, take :data:`TABLE_SIZE` inverse-CDF points,
+scale by :data:`NETEM_DIST_SCALE` and clamp to int16.
+
+Usage (module CLI)::
+
+    python -m rosotacom.netem_dist samples.csv --column delay_ms --out field.dist
+
+The output installs as ``/usr/lib/tc/field.dist`` and is then addressable as
+``distribution: field`` (with ``distribution_file`` pointing at the file, so
+profile runners install it into the shaping netns themselves).
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import math
+from collections.abc import Sequence
+from pathlib import Path
+
+NETEM_DIST_SCALE = 8192  # kernel: delay = mu + sigma * table[r] / 8192
+TABLE_SIZE = 4096  # entries in the shipped iproute2 tables
+_INT16_MIN, _INT16_MAX = -32768, 32767
+
+
+def build_dist_table(samples: Sequence[float], *, table_size: int = TABLE_SIZE) -> list[int]:
+    """Inverse-CDF table of the normalized ``samples`` (int16, netem scaling)."""
+    values = sorted(float(x) for x in samples if math.isfinite(float(x)))
+    if len(values) < 100:
+        raise ValueError(f"need at least 100 finite samples for a stable table, got {len(values)}")
+    mean = sum(values) / len(values)
+    var = sum((x - mean) ** 2 for x in values) / len(values)
+    sigma = math.sqrt(var)
+    if sigma <= 0:
+        raise ValueError("samples have zero spread; a distribution table is meaningless")
+    table: list[int] = []
+    n = len(values)
+    for i in range(table_size):
+        # midpoint quantile of bucket i, linearly interpolated in the sorted samples
+        q = (i + 0.5) / table_size
+        pos = q * (n - 1)
+        lo = int(pos)
+        frac = pos - lo
+        x = values[lo] if lo + 1 >= n else values[lo] * (1 - frac) + values[lo + 1] * frac
+        z = (x - mean) / sigma
+        table.append(max(_INT16_MIN, min(_INT16_MAX, round(z * NETEM_DIST_SCALE))))
+    return table
+
+
+def format_dist_file(table: Sequence[int], *, comment: str | None = None) -> str:
+    """Render a table in the ``/usr/lib/tc/*.dist`` text format (8 values/line)."""
+    lines = [f"# {line}" for line in (comment or "").splitlines() if line]
+    for i in range(0, len(table), 8):
+        lines.append(" ".join(f"{v:d}" for v in table[i : i + 8]))
+    return "\n".join(lines) + "\n"
+
+
+def read_samples_csv(path: str | Path, column: str) -> list[float]:
+    out: list[float] = []
+    with open(path, newline="", encoding="utf-8") as fp:
+        reader = csv.DictReader(fp)
+        if reader.fieldnames is None or column not in reader.fieldnames:
+            raise ValueError(f"{path}: no column {column!r}; columns: {reader.fieldnames}")
+        for row in reader:
+            text = (row.get(column) or "").strip()
+            if text:
+                try:
+                    out.append(float(text))
+                except ValueError:
+                    continue
+    return out
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("samples_csv", help="CSV with one numeric column of delay samples")
+    parser.add_argument("--column", default="delay_ms", help="column to read (default: delay_ms)")
+    parser.add_argument("--out", required=True, help="output .dist path (basename = table name)")
+    parser.add_argument("--comment", default=None, help="provenance line(s) for the file header")
+    args = parser.parse_args(argv)
+    samples = read_samples_csv(args.samples_csv, args.column)
+    table = build_dist_table(samples)
+    comment = args.comment or (
+        f"generated by rosotacom.netem_dist from {Path(args.samples_csv).name} ({len(samples)} samples)"
+    )
+    Path(args.out).write_text(format_dist_file(table, comment=comment), encoding="utf-8")
+    print(f"wrote {args.out}: {len(table)} entries from {len(samples)} samples")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev42}/src/rosotacom/network_profiles.py

@@ -136,6 +136,38 @@ def parse_seed(value: Any, what: str = "seed") -> int:
 # Schema
 # --------------------------------------------------------------------------- #
 
+# Distribution tables iproute2 ships; anything else needs a ``distribution_file``
+# that the runner installs into the shaping netns as ``/usr/lib/tc/<name>.dist``.
+_BUILTIN_DISTRIBUTIONS = ("normal", "pareto", "paretonormal")
+_DISTRIBUTION_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+
+
+@dataclass(frozen=True)
+class GemodelLoss:
+    """netem ``loss gemodel`` — the Gilbert(-Elliott) two-state loss process.
+
+    Per-*packet* state transitions (netem evaluates the chain once per packet):
+    ``p_pct`` = P(good→bad), ``r_pct`` = P(bad→good), ``loss_bad_pct`` = loss
+    probability while bad (netem's ``1-h`` argument), ``loss_good_pct`` = loss
+    probability while good (netem's ``1-k``). All four are always emitted, so the
+    argv never depends on iproute2 defaults. This is the vocabulary the plain
+    2-arg ``loss p% corr%`` cannot express: short intense bad states inside long
+    clean good states, as measured on real cellular links.
+    """
+
+    p_pct: float
+    r_pct: float
+    loss_bad_pct: float = 100.0
+    loss_good_pct: float = 0.0
+
+    def __post_init__(self) -> None:
+        for name in ("p_pct", "r_pct", "loss_bad_pct", "loss_good_pct"):
+            value = getattr(self, name)
+            if not 0.0 <= value <= 100.0:
+                raise ValueError(f"gemodel {name} must be within [0, 100]%, got {value!r}")
+        if self.p_pct == 0.0 and self.loss_good_pct == 0.0:
+            raise ValueError("gemodel with p=0 and loss_good=0 never loses anything; drop the block instead")
+
 
 @dataclass(frozen=True)
 class DirectionShaping:
@@ -145,9 +177,11 @@ class DirectionShaping:
     rate_bps: float | None = None
     delay_ms: float | None = None
     jitter_ms: float | None = None
-    distribution: str | None = None  # normal | pareto | paretonormal (needs jitter)
+    distribution: str | None = None  # builtin (normal|pareto|paretonormal) or a custom table name
+    distribution_file: str | None = None  # .dist file for a custom table (installed as /usr/lib/tc/<name>.dist)
     loss_pct: float | None = None
     loss_correlation_pct: float | None = None  # netem correlated loss (needs loss)
+    loss_gemodel: GemodelLoss | None = None  # netem Gilbert-Elliott loss (exclusive with loss)
     reorder_pct: float | None = None  # netem reorder (needs delay)
     duplicate_pct: float | None = None
     seed: int | None = None
@@ -156,23 +190,29 @@ class DirectionShaping:
 
     @property
     def is_empty(self) -> bool:
-        return all(
-            getattr(self, name) is None
-            for name in (
-                "rate_bps",
-                "delay_ms",
-                "jitter_ms",
-                "loss_pct",
-                "reorder_pct",
-                "duplicate_pct",
+        return (
+            all(
+                getattr(self, name) is None
+                for name in (
+                    "rate_bps",
+                    "delay_ms",
+                    "jitter_ms",
+                    "loss_pct",
+                    "reorder_pct",
+                    "duplicate_pct",
+                )
             )
+            and self.loss_gemodel is None
         )
 
     @property
     def has_netem(self) -> bool:
-        return any(
-            getattr(self, name) is not None
-            for name in ("delay_ms", "jitter_ms", "loss_pct", "reorder_pct", "duplicate_pct")
+        return (
+            any(
+                getattr(self, name) is not None
+                for name in ("delay_ms", "jitter_ms", "loss_pct", "reorder_pct", "duplicate_pct")
+            )
+            or self.loss_gemodel is not None
         )
 
     def __post_init__(self) -> None:
@@ -182,10 +222,21 @@ class DirectionShaping:
             raise ValueError("distribution requires a jitter")
         if self.loss_correlation_pct is not None and self.loss_pct is None:
             raise ValueError("loss_correlation requires a loss")
+        if self.loss_gemodel is not None and self.loss_pct is not None:
+            raise ValueError("loss_gemodel and loss are exclusive: one loss model per direction")
         if self.reorder_pct is not None and self.delay_ms is None:
             raise ValueError("reorder requires a delay (netem reorders within the delay window)")
-        if self.distribution is not None and self.distribution not in ("normal", "pareto", "paretonormal"):
-            raise ValueError(f"unsupported distribution {self.distribution!r}")
+        if self.distribution is not None:
+            if not _DISTRIBUTION_NAME_RE.fullmatch(self.distribution):
+                raise ValueError(f"unsupported distribution name {self.distribution!r}")
+            if self.distribution not in _BUILTIN_DISTRIBUTIONS and self.distribution_file is None:
+                raise ValueError(
+                    f"distribution {self.distribution!r} is not built into iproute2 "
+                    f"({', '.join(_BUILTIN_DISTRIBUTIONS)}); give distribution_file so the "
+                    "runner can install /usr/lib/tc/" + self.distribution + ".dist"
+                )
+        if self.distribution_file is not None and self.distribution is None:
+            raise ValueError("distribution_file requires a distribution name")
 
 
 @dataclass(frozen=True)
@@ -235,8 +286,10 @@ _DIRECTION_KEYS = frozenset(
         "delay",
         "jitter",
         "distribution",
+        "distribution_file",
         "loss",
         "loss_correlation",
+        "loss_gemodel",
         "reorder",
         "duplicate",
         "seed",
@@ -245,6 +298,26 @@ _DIRECTION_KEYS = frozenset(
     }
 )
 
+_GEMODEL_KEYS = frozenset({"p", "r", "loss_bad", "loss_good"})
+
+
+def parse_gemodel(spec: Mapping[str, Any]) -> GemodelLoss:
+    """Parse a ``loss_gemodel`` block (``p``/``r`` required, loss_bad/loss_good optional)."""
+    if not isinstance(spec, Mapping):
+        raise ValueError(f"loss_gemodel: expected a mapping with p/r[/loss_bad/loss_good], got {spec!r}")
+    unknown = sorted(set(spec) - _GEMODEL_KEYS)
+    if unknown:
+        raise ValueError(f"unsupported loss_gemodel keys {unknown}; allowed: {sorted(_GEMODEL_KEYS)}")
+    missing = sorted({"p", "r"} - set(spec))
+    if missing:
+        raise ValueError(f"loss_gemodel requires {missing}")
+    return GemodelLoss(
+        p_pct=parse_pct(spec["p"], "loss_gemodel p"),
+        r_pct=parse_pct(spec["r"], "loss_gemodel r"),
+        loss_bad_pct=parse_pct(spec["loss_bad"], "loss_gemodel loss_bad") if "loss_bad" in spec else 100.0,
+        loss_good_pct=parse_pct(spec["loss_good"], "loss_gemodel loss_good") if "loss_good" in spec else 0.0,
+    )
+
 
 def parse_direction(spec: Mapping[str, Any] | None) -> DirectionShaping | None:
     """Parse one ``uplink``/``downlink`` block into a :class:`DirectionShaping`."""
@@ -258,10 +331,12 @@ def parse_direction(spec: Mapping[str, Any] | None) -> DirectionShaping | None:
         delay_ms=parse_ms(spec["delay"], "delay") if "delay" in spec else None,
         jitter_ms=parse_ms(spec["jitter"], "jitter") if "jitter" in spec else None,
         distribution=str(spec["distribution"]) if "distribution" in spec else None,
+        distribution_file=str(spec["distribution_file"]) if "distribution_file" in spec else None,
         loss_pct=parse_pct(spec["loss"], "loss") if "loss" in spec else None,
         loss_correlation_pct=(
             parse_pct(spec["loss_correlation"], "loss_correlation") if "loss_correlation" in spec else None
         ),
+        loss_gemodel=parse_gemodel(spec["loss_gemodel"]) if "loss_gemodel" in spec else None,
         reorder_pct=parse_pct(spec["reorder"], "reorder") if "reorder" in spec else None,
         duplicate_pct=parse_pct(spec["duplicate"], "duplicate") if "duplicate" in spec else None,
         seed=parse_seed(spec["seed"], "seed") if "seed" in spec else None,
@@ -330,13 +405,71 @@ def parse_profiles(doc: Mapping[str, Any]) -> dict[str, Profile]:
 
 
 def load_profiles_file(path: str | Path) -> dict[str, Profile]:
-    """Load a project-scoped ``profiles.yaml`` into ``{name: Profile}``."""
+    """Load a project-scoped ``profiles.yaml`` into ``{name: Profile}``.
+
+    Relative ``distribution_file`` entries are resolved against the profiles
+    file's own directory, so a profiles file stays self-contained wherever the
+    project is checked out.
+    """
     import yaml
 
     doc = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
     if not isinstance(doc, Mapping):
         raise ValueError(f"{path}: profiles file must be a mapping (with a top-level 'profiles:' block)")
-    return parse_profiles(doc)
+    profiles = parse_profiles(doc)
+    base = Path(path).resolve().parent
+    return {name: _resolve_distribution_files(profile, base) for name, profile in profiles.items()}
+
+
+def _resolve_distribution_files(profile: Profile, base: Path) -> Profile:
+    from dataclasses import replace
+
+    def fix(shaping: DirectionShaping | None) -> DirectionShaping | None:
+        if shaping is None or shaping.distribution_file is None:
+            return shaping
+        file = Path(shaping.distribution_file)
+        if not file.is_absolute():
+            file = base / file
+        return replace(shaping, distribution_file=str(file))
+
+    if profile.is_timeline:
+        segments = tuple(
+            replace(segment, uplink=fix(segment.uplink), downlink=fix(segment.downlink)) for segment in profile.timeline
+        )
+        return replace(profile, timeline=segments)
+    return replace(profile, uplink=fix(profile.uplink), downlink=fix(profile.downlink))
+
+
+def required_dist_installs(profile: Profile) -> list[tuple[str, str]]:
+    """``(table_name, file_path)`` pairs a runner must install as
+    ``/usr/lib/tc/<table_name>.dist`` inside the shaping netns before arming.
+
+    Builtin distributions need nothing; duplicates collapse; conflicting files
+    for one name are an error (two segments must mean the same table).
+    """
+    found: dict[str, str] = {}
+
+    def visit(shaping: DirectionShaping | None) -> None:
+        if shaping is None or shaping.distribution is None:
+            return
+        if shaping.distribution in _BUILTIN_DISTRIBUTIONS or shaping.distribution_file is None:
+            return
+        existing = found.get(shaping.distribution)
+        if existing is not None and existing != shaping.distribution_file:
+            raise ValueError(
+                f"distribution {shaping.distribution!r} maps to two files: {existing!r} and "
+                f"{shaping.distribution_file!r}"
+            )
+        found[shaping.distribution] = shaping.distribution_file
+
+    if profile.is_timeline:
+        for segment in profile.timeline:
+            visit(segment.uplink)
+            visit(segment.downlink)
+    else:
+        visit(profile.uplink)
+        visit(profile.downlink)
+    return sorted(found.items())
 
 
 # Selecting nothing — the unshaped rung (0/1) or the "no emulation" sentinel.
@@ -400,6 +533,18 @@ def _netem_args(shaping: DirectionShaping) -> list[str]:
         args += ["loss", _pct(shaping.loss_pct)]
         if shaping.loss_correlation_pct is not None:
             args.append(_pct(shaping.loss_correlation_pct))
+    if shaping.loss_gemodel is not None:
+        gem = shaping.loss_gemodel
+        # netem's positional names are p, r, 1-h, 1-k: the 3rd/4th arguments ARE
+        # the loss probabilities in bad/good state. All four always emitted.
+        args += [
+            "loss",
+            "gemodel",
+            _pct(gem.p_pct),
+            _pct(gem.r_pct),
+            _pct(gem.loss_bad_pct),
+            _pct(gem.loss_good_pct),
+        ]
     if shaping.duplicate_pct is not None:
         args += ["duplicate", _pct(shaping.duplicate_pct)]
     if shaping.reorder_pct is not None:

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev42}/src/rosotacom_dev.egg-info/PKG-INFO

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

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev42}/src/rosotacom_dev.egg-info/SOURCES.txt

@@ -101,6 +101,7 @@ src/rosotacom/ffmpeg_packet.py
 src/rosotacom/forensics.py
 src/rosotacom/geomap.py
 src/rosotacom/image_cache.py
+src/rosotacom/netem_dist.py
 src/rosotacom/network_profiles.py
 src/rosotacom/network_shaper.py
 src/rosotacom/plots.py
@@ -331,6 +332,7 @@ tests/unit/test_geomap.py
 tests/unit/test_image_cache.py
 tests/unit/test_link_bytes.py
 tests/unit/test_link_trace.py
+tests/unit/test_netem_dist.py
 tests/unit/test_network_profiles.py
 tests/unit/test_network_shaper.py
 tests/unit/test_ota_unwrapper.py

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev42}/src/rosotacom_dev.egg-info/scm_file_list.json

@@ -103,6 +103,7 @@
     "src/rosotacom/forensics.py",
     "src/rosotacom/geomap.py",
     "src/rosotacom/image_cache.py",
+    "src/rosotacom/netem_dist.py",
     "src/rosotacom/network_profiles.py",
     "src/rosotacom/network_shaper.py",
     "src/rosotacom/plots.py",
@@ -326,6 +327,7 @@
     "tests/unit/test_image_cache.py",
     "tests/unit/test_link_bytes.py",
     "tests/unit/test_link_trace.py",
+    "tests/unit/test_netem_dist.py",
     "tests/unit/test_network_profiles.py",
     "tests/unit/test_network_shaper.py",
     "tests/unit/test_ota_unwrapper.py",

{rosotacom_dev-2.5.dev41 → rosotacom_dev-2.5.dev42}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 41,
-  "node": "gbe160fa2bbb0b0fe47c4bdc3c64a7334ef1ddfef",
+  "distance": 42,
+  "node": "g3227daf2639025d14d15f043afdb0b78742f7142",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-18"

rosotacom_dev-2.5.dev42/tests/unit/test_netem_dist.py

@@ -0,0 +1,62 @@
+"""netem distribution-table generation (rosotacom.netem_dist) — host tests."""
+
+from __future__ import annotations
+
+import math
+import random
+
+import pytest
+
+from rosotacom.netem_dist import (
+    NETEM_DIST_SCALE,
+    TABLE_SIZE,
+    build_dist_table,
+    format_dist_file,
+    read_samples_csv,
+)
+
+
+def test_table_shape_and_normalization() -> None:
+    rng = random.Random(1)
+    samples = [rng.gauss(30.0, 10.0) for _ in range(20000)]
+    table = build_dist_table(samples)
+    assert len(table) == TABLE_SIZE
+    assert table == sorted(table)  # inverse CDF is nondecreasing
+    mean = sum(table) / len(table)
+    std = math.sqrt(sum((v - mean) ** 2 for v in table) / len(table))
+    # normalized to mean 0 / std 1 in units of NETEM_DIST_SCALE
+    assert abs(mean) < 0.05 * NETEM_DIST_SCALE
+    assert abs(std - NETEM_DIST_SCALE) < 0.05 * NETEM_DIST_SCALE
+
+
+def test_table_preserves_a_heavy_tail() -> None:
+    # A lognormal delay (field cellular links) must keep its asymmetry: the
+    # upper tail reaches much further from the median than the lower tail.
+    rng = random.Random(2)
+    samples = [math.exp(rng.gauss(3.3, 0.6)) for _ in range(20000)]
+    table = build_dist_table(samples)
+    p50 = table[TABLE_SIZE // 2]
+    upper = table[int(TABLE_SIZE * 0.999)] - p50
+    lower = p50 - table[int(TABLE_SIZE * 0.001)]
+    assert upper > 1.8 * lower
+
+
+def test_rejects_degenerate_input() -> None:
+    with pytest.raises(ValueError):
+        build_dist_table([1.0] * 500)  # zero spread
+    with pytest.raises(ValueError):
+        build_dist_table([1.0, 2.0])  # too few samples
+
+
+def test_format_and_csv_roundtrip(tmp_path) -> None:
+    csv_path = tmp_path / "samples.csv"
+    csv_path.write_text("delay_ms\n" + "\n".join(str(10 + (i % 50)) for i in range(500)) + "\n", encoding="utf-8")
+    samples = read_samples_csv(csv_path, "delay_ms")
+    assert len(samples) == 500
+    text = format_dist_file(build_dist_table(samples), comment="prov line")
+    lines = text.strip().splitlines()
+    assert lines[0] == "# prov line"
+    values = [int(v) for line in lines[1:] for v in line.split()]
+    assert len(values) == TABLE_SIZE
+    with pytest.raises(ValueError):
+        read_samples_csv(csv_path, "missing_column")