rosotacom-dev 2.5.dev67__tar.gz → 2.5.dev69__tar.gz

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev67
+Version: 2.5.dev69
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -689,7 +689,8 @@ is which fragment was lost, whether a retransmit followed, or how one sample's
 sub-messages were spaced, enable the [header-only OTA capture](docs/ota-pcap.md)
 next to them — `shared.ota_pcap.enabled`, off by default, roughly 1 % of payload
 volume, and every packet labelled uplink or downlink. It needs no capability,
-no image change and no extra container.
+no image change and no extra container — only the passwordless sudo the
+container already has, and only until its socket is open.
 
 Convert a recorded link trace into a profiles-file entry when you want to replay
 the same drive conditions in a repeatable benchmark:

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/README.md

@@ -644,7 +644,8 @@ is which fragment was lost, whether a retransmit followed, or how one sample's
 sub-messages were spaced, enable the [header-only OTA capture](docs/ota-pcap.md)
 next to them — `shared.ota_pcap.enabled`, off by default, roughly 1 % of payload
 volume, and every packet labelled uplink or downlink. It needs no capability,
-no image change and no extra container.
+no image change and no extra container — only the passwordless sudo the
+container already has, and only until its socket is open.
 
 Convert a recorded link trace into a profiles-file entry when you want to replay
 the same drive conditions in a repeatable benchmark:

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/docs/ota-pcap.md

@@ -110,9 +110,25 @@ runs on. `shared.ota_pcap.enabled` therefore requires
 
 ## Privilege, containers, and what the option costs
 
-Nothing is added. The communication container already runs as root with
-`CAP_NET_RAW` in docker's default set, so the capture needs no `--cap-add`, no
-image change, no rebuild and no extra container in `docker ps`.
+No image change, no rebuild, no added capability and no extra container in
+`docker ps`. What it does need is `sudo`, and only until the socket is open.
+
+ros2docker's entrypoint runs this container's processes as `containeruser`,
+whose `CapEff` is `0000000000000000`. A non-root process cannot open an
+`AF_PACKET` socket however the container was started, so `--cap-add NET_RAW`
+would buy nothing. `containeruser` does have passwordless sudo here — the NET
+pane's `sudo iftop` already depends on it — so the capture is launched through
+it, and `--drop-to` hands the process back to `containeruser` the moment the
+socket exists. The pcap therefore belongs to the same user as
+`link_trace.jsonl` beside it, rather than to root.
+
+Two earlier attempts at this assumed root from a `docker run` that bypassed the
+entrypoint, and were wrong in the same way both times. If you change this,
+check the **running** container:
+
+```bash
+docker exec <com-container> bash -lc 'id; grep CapEff /proc/self/status'
+```
 
 `CAP_NET_ADMIN` is *not* taken and is not needed: it buys promiscuous mode,
 which this capture deliberately does not use. Everything of interest is

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/src/rosotacom/resources/ws/ros2src/com_py/com_py/ota_pcap.py

@@ -35,9 +35,22 @@ to a 6 Mbit/s link and survived a field session (#267). A capture that has to
 re-derive link knowledge is in the wrong place; this one asks the same
 resolution the status snapshot's own link block uses.
 
-It also needs no privilege here. This container already runs as root with
-`CAP_NET_RAW` in the default docker set, so the option adds no capability, no
-image change and no container.
+WHAT IT NEEDS, MEASURED RATHER THAN ASSUMED
+-------------------------------------------
+`sudo`, and only until the socket is open. ros2docker's entrypoint runs this
+container's processes as `containeruser`, whose `CapEff` is
+0000000000000000 — a non-root process cannot open an `AF_PACKET` socket
+however the container was started, so `--cap-add` buys nothing. `containeruser`
+does have passwordless sudo here, which the NET pane's `sudo iftop` already
+relies on, so the capture is launched through it and `--drop-to` hands the
+process back to `containeruser` the moment the socket exists. The pcap in
+`logs/<peer>/status/` therefore belongs to the same user as `link_trace.jsonl`
+beside it.
+
+That is the whole cost: no image change, no rebuild, no added capability and no
+extra container. Two earlier attempts at this assumed root from a `docker run`
+that bypassed the entrypoint, and both were wrong in the same way — check the
+*running* container, not the image.
 
 THE FILE
 --------
@@ -72,6 +85,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import signal
 import socket
 import struct
@@ -240,6 +254,40 @@ def open_socket(iface: str) -> socket.socket:
     return sock
 
 
+def drop_privileges(spec: str | None) -> str | None:
+    """Hand the process back to the user that started it.
+
+    The capture is launched through `sudo` — see the module header — because a
+    non-root process cannot open an `AF_PACKET` socket. Nothing after that call
+    needs root, and the artifacts in `logs/<peer>/status/` belong to
+    `containeruser` like `link_trace.jsonl` beside them: a root-owned file in
+    that directory is a `sudo rm` waiting to happen months later, and
+    `gather_drive.py` would copy it without noticing.
+
+    `spec` is "uid:gid". An argument rather than an environment variable
+    because sudo does not pass the environment through. Returns what it did, or
+    None when there was nothing to do.
+    """
+    if not spec:
+        return None
+    try:
+        uid_text, _, gid_text = spec.partition(":")
+        uid, gid = int(uid_text), int(gid_text or uid_text)
+    except ValueError:
+        log(f"WARN --drop-to {spec!r} is not uid:gid — staying as I am")
+        return None
+    if os.geteuid() != 0:
+        return None
+    try:
+        os.setgroups([])
+        os.setgid(gid)
+        os.setuid(uid)
+    except OSError as error:
+        log(f"WARN could not drop to {uid}:{gid} ({error}) — the file will be root's")
+        return None
+    return f"{uid}:{gid}"
+
+
 def kernel_timestamp(ancdata) -> tuple[int, int] | None:
     """(seconds, microseconds) out of SCM_TIMESTAMPNS, if the kernel sent it."""
     for level, kind, data in ancdata:
@@ -264,7 +312,9 @@ class Capture:
     """One pcap file, and the counts needed to trust it."""
 
     def __init__(self, iface: str, out: Path, *, snaplen: int = DEFAULT_SNAPLEN,
-                 peer: str | None = None, max_bytes: int = DEFAULT_MAX_MB * 1000 * 1000):
+                 peer: str | None = None, max_bytes: int = DEFAULT_MAX_MB * 1000 * 1000,
+                 drop_to: str | None = None):
+        self.drop_to = drop_to
         self.iface = iface
         self.out = out
         self.snaplen = snaplen
@@ -300,6 +350,10 @@ class Capture:
 
     def run(self, stop: list) -> None:
         sock = open_socket(self.iface)
+        # Root was needed for that one call and for nothing after it.
+        dropped = drop_privileges(self.drop_to)
+        if dropped:
+            log(f"privileges dropped to {dropped}; the socket stays open")
         packet_statistics(sock)  # zero the counters; the run owns them from here
         ancillary = socket.CMSG_SPACE(16)
         self.out.parent.mkdir(parents=True, exist_ok=True)
@@ -365,10 +419,13 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--peer", help="keep only packets to or from this address")
     parser.add_argument("--max-mb", type=int, default=DEFAULT_MAX_MB,
                         help=f"stop after this many MB (default {DEFAULT_MAX_MB})")
+    parser.add_argument("--drop-to", metavar="UID:GID",
+                        help="give root back once the socket is open, so the pcap "
+                             "belongs to the user that started the session")
     args = parser.parse_args(argv)
 
     capture = Capture(args.iface, args.out, snaplen=args.snaplen, peer=args.peer,
-                      max_bytes=args.max_mb * 1000 * 1000)
+                      max_bytes=args.max_mb * 1000 * 1000, drop_to=args.drop_to)
 
     stop: list = []
     for name in (signal.SIGINT, signal.SIGTERM):
@@ -379,9 +436,10 @@ def main(argv: list[str] | None = None) -> int:
     try:
         capture.run(stop)
     except PermissionError:
-        log("FAIL no permission to open a packet socket. Inside the recorder "
-            "container this should not happen — CAP_NET_RAW is in docker's "
-            "default set. Outside it, run as root.")
+        log("FAIL no permission to open a packet socket. This is meant to run "
+            "through `sudo` from inside the communication container, where "
+            "containeruser has passwordless sudo; a non-root process cannot "
+            "open AF_PACKET whatever capabilities the container was given.")
         return 3
     except OSError as error:
         log(f"FAIL {error}")

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/src/rosotacom/resources/ws/ros2src/com_py/com_py/status_overview.py

@@ -564,6 +564,9 @@ class StatusOverview(Node):
             "--out", path,
             "--snaplen", str(int(self.get_parameter("ota_pcap_snaplen").value)),
             "--max-mb", str(int(self.get_parameter("ota_pcap_max_mb").value)),
+            # Root opens the socket; this hands it straight back, so the pcap
+            # belongs to the same user as link_trace.jsonl beside it.
+            "--drop-to", f"{os.getuid()}:{os.getgid()}",
         ]
         # Narrowed to the remote peer by default. On a VPN tunnel the whole
         # device is the link and the filter changes nothing; on a LAN port it
@@ -573,6 +576,16 @@ class StatusOverview(Node):
         if bool(self.get_parameter("ota_pcap_peer_filter").value) and peer_ip:
             argv += ["--peer", peer_ip]
 
+        # An `AF_PACKET` socket needs root, and this node is `containeruser`:
+        # its `CapEff` is zero, so no `--cap-add` on the container would help.
+        # `containeruser` has passwordless sudo here — the NET pane's
+        # `sudo iftop` already depends on it — so the capture goes through it
+        # and gives root back as soon as the socket exists. Where there is no
+        # sudo (this module run somewhere else, or already as root) the plain
+        # command is tried instead rather than refused.
+        if os.geteuid() != 0 and self._sudo_available():
+            argv = ["sudo", "-n", *argv]
+
         try:
             self._pcap = subprocess.Popen(argv, start_new_session=True)
         except OSError as exc:  # noqa: BLE001 - a sidecar may not stop a session
@@ -588,6 +601,16 @@ class StatusOverview(Node):
                bool(self.get_parameter("ota_pcap_peer_filter").value) else "")
         )
 
+    @staticmethod
+    def _sudo_available() -> bool:
+        """Can this process become root without being asked for a password?"""
+        try:
+            return subprocess.run(
+                ["sudo", "-n", "true"], capture_output=True, timeout=5.0
+            ).returncode == 0
+        except (OSError, subprocess.SubprocessError):
+            return False
+
     def _stop_ota_pcap(self) -> None:
         """SIGINT and wait, so the sidecar JSON and the drop counts are written.
 
@@ -599,7 +622,15 @@ class StatusOverview(Node):
         if child is None or child.poll() is not None:
             return
         try:
-            child.send_signal(signal.SIGINT)
+            # Through sudo the child is root, so an ordinary kill would be
+            # refused; `sudo -n kill` is how a non-root parent signals it.
+            # SIGINT and not SIGTERM, because SIGINT is what makes the capture
+            # write ota.json on the way out.
+            if os.geteuid() != 0:
+                subprocess.run(["sudo", "-n", "kill", "-INT", str(child.pid)],
+                               capture_output=True, timeout=5.0)
+            else:
+                child.send_signal(signal.SIGINT)
             child.wait(timeout=20.0)
         except subprocess.TimeoutExpired:
             child.kill()

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev67
+Version: 2.5.dev69
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -689,7 +689,8 @@ is which fragment was lost, whether a retransmit followed, or how one sample's
 sub-messages were spaced, enable the [header-only OTA capture](docs/ota-pcap.md)
 next to them — `shared.ota_pcap.enabled`, off by default, roughly 1 % of payload
 volume, and every packet labelled uplink or downlink. It needs no capability,
-no image change and no extra container.
+no image change and no extra container — only the passwordless sudo the
+container already has, and only until its socket is open.
 
 Convert a recorded link trace into a profiles-file entry when you want to replay
 the same drive conditions in a repeatable benchmark:

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/src/rosotacom_dev.egg-info/SOURCES.txt

@@ -386,6 +386,7 @@ tests/unit/test_status_eval.py
 tests/unit/test_status_overview.py
 tests/unit/test_status_overview_observer.py
 tests/unit/test_stream_stats.py
+tests/unit/test_terminology_stage_ownership.py
 tests/unit/test_trace_profiles.py
 tests/unit/test_transit.py
 tests/unit/test_video_quality.py

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/src/rosotacom_dev.egg-info/scm_file_list.json

@@ -381,6 +381,7 @@
     "tests/unit/test_status_overview.py",
     "tests/unit/test_status_overview_observer.py",
     "tests/unit/test_stream_stats.py",
+    "tests/unit/test_terminology_stage_ownership.py",
     "tests/unit/test_trace_profiles.py",
     "tests/unit/test_transit.py",
     "tests/unit/test_video_quality.py"

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
   "tag": "2.4",
-  "distance": 67,
-  "node": "g66ad66a5a0a3d15dec65006745d88e43757f6c72",
+  "distance": 69,
+  "node": "g429a2536fa56d96c76f3c306809f3dc6864f051e",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/terminology.md

@@ -305,6 +305,9 @@ Notes:
 - Preprocessing/postprocessing are just processing stages applied at different points:
   - outbound: native → processed (optional)
   - inbound: processed → native (optional)
+- Being postprocessing does **not** by itself make a transformation a processing
+  stage of this project. Which transformations belong here is decided by
+  §9.1, not by where or when they run.
 
 ---
 
@@ -323,6 +326,57 @@ Example: `/com/out/A/to_B/sensors/camera/image_raw/restamped/max20hz/bz2`
 
 ## 9. Module responsibilities
 
+### 9.1 Stage ownership (which transformations belong to this project)
+
+A **processing stage** (§7) belongs to this project when it either
+
+1. **undoes a stage this project applied** — decompression undoes compression,
+   the OTA unwrapper undoes the OTA wrapper, `global_to_local` undoes
+   `local_to_global`, `trickle` undoes `latch`; or
+2. **compensates for the medium** — the playout pacer against the arrival
+   jitter a link introduces.
+
+Everything else that happens to a stream after the inbound native topic
+belongs to whoever consumes it, and is that consumer's code in that
+consumer's repository. The inbound native topic (§3) is where this project's
+canonical lifecycle ends, and stage ownership ends with it.
+
+**Two criteria that do not decide it**, because both are true of stages on
+either side:
+
+- *Where it runs.* Decompression, the unwrapper, `trickle` and the pacer all
+  run at the receiving peer. So does an application transform that has nothing
+  to do with the link.
+- *That it is postprocessing.* §3 names inbound postprocessing as part of the
+  lifecycle, so the word describes a position, not an owner.
+
+`trickle` is the stage that makes the boundary feel ambiguous, and rule 1
+resolves it. It can be read as a fix for a consumer that expects a periodic
+stream — but the question is not what it is good for, it is why the value was
+latched in the first place: repeating a state at a fixed rate over a metered
+link is waste, so latching is a link decision and `trickle` is its inverse.
+Without the link there would be nothing to un-latch.
+
+**The quick test is a counterfactual.** Change the *link* — other radio, other
+route, other codec — and ask whether the stage has to change; then change the
+*consumer* — other display, other viewer, an automated pipeline instead of a
+person — and ask the same. A stage that survives every link change and breaks
+on a consumer change is the consumer's.
+
+**The falsifiable test, for cases the counterfactual leaves open.** A stage
+here becomes part of the session contract, so it must carry an `expect:` the
+harness can assert. If no `hz`, `loss_pct`, `latency_ms` or
+`completeness.vs_bag_ratio` on that stage would mean anything, the contract
+cannot check it — and a stage the contract cannot check does not belong in the
+contract.
+
+This is about **stages, not about code**. A generic operation — resampling an
+image, filtering a point cloud — may live here as a reusable node the day a
+second session needs it. What must not move here is the decision that a
+particular consumer wants a particular result.
+
+---
+
 ### App Relay
 The **App Relay** (application relay) maps between application topics and com topics.
 

{rosotacom_dev-2.5.dev67 → rosotacom_dev-2.5.dev69}/tests/unit/test_ota_pcap.py

@@ -306,3 +306,52 @@ def test_the_node_is_handed_the_remote_peers_address_to_narrow_the_capture() ->
     other conversation the machine is having."""
     text = PLUGIN_BASE.read_text(encoding="utf-8")
     assert "-p ota_pcap_peer_ip:=${ip_remote}" in text
+
+
+# ---------------------------------------------------------------------------
+# root for one system call
+# ---------------------------------------------------------------------------
+
+
+def test_the_capture_gives_root_back_as_soon_as_the_socket_exists(monkeypatch) -> None:
+    """Launched through sudo, dropped straight after — so the pcap belongs to
+    the same user as `link_trace.jsonl` beside it, not to root."""
+    calls = {}
+    monkeypatch.setattr(ota_pcap.os, "geteuid", lambda: 0)
+    monkeypatch.setattr(ota_pcap.os, "setgroups", lambda g: calls.setdefault("groups", g))
+    monkeypatch.setattr(ota_pcap.os, "setgid", lambda gid: calls.setdefault("gid", gid))
+    monkeypatch.setattr(ota_pcap.os, "setuid", lambda uid: calls.setdefault("uid", uid))
+
+    assert ota_pcap.drop_privileges("1000:1001") == "1000:1001"
+    assert calls == {"groups": [], "gid": 1001, "uid": 1000}
+
+
+def test_a_capture_that_is_not_root_leaves_the_ids_alone(monkeypatch) -> None:
+    monkeypatch.setattr(ota_pcap.os, "geteuid", lambda: 1000)
+    monkeypatch.setattr(ota_pcap.os, "setuid", lambda uid: pytest.fail("must not be called"))
+    assert ota_pcap.drop_privileges("1000:1000") is None
+
+
+@pytest.mark.parametrize("spec", [None, "", "root", "1000:nobody"])
+def test_a_spec_that_is_not_uid_gid_never_changes_the_process(spec, monkeypatch) -> None:
+    monkeypatch.setattr(ota_pcap.os, "geteuid", lambda: 0)
+    monkeypatch.setattr(ota_pcap.os, "setuid", lambda uid: pytest.fail("must not be called"))
+    assert ota_pcap.drop_privileges(spec) is None
+
+
+def test_the_node_launches_it_through_sudo_and_hands_root_straight_back() -> None:
+    """The node runs as `containeruser`, whose CapEff is zero, so no `--cap-add`
+    on the container would let it open an AF_PACKET socket. Asserted over the
+    source because the node needs rclpy, which the host suite does not have."""
+    source = (WS_PY / "com_py" / "status_overview.py").read_text(encoding="utf-8")
+    assert 'argv = ["sudo", "-n", *argv]' in source
+    assert '"--drop-to", f"{os.getuid()}:{os.getgid()}"' in source
+    # And the stop goes the same way: the child is root, so an ordinary kill
+    # would be refused — and it must be SIGINT, which is what writes ota.json.
+    assert '"sudo", "-n", "kill", "-INT"' in source
+
+
+def test_the_capture_is_a_process_not_a_thread_in_the_status_node() -> None:
+    """A capture that misbehaves must not reach the snapshot an operator watches."""
+    source = (WS_PY / "com_py" / "status_overview.py").read_text(encoding="utf-8")
+    assert "subprocess.Popen(argv, start_new_session=True)" in source

rosotacom_dev-2.5.dev69/tests/unit/test_terminology_stage_ownership.py

@@ -0,0 +1,103 @@
+"""The stage-ownership rule in `terminology.md` §9.1, against the code.
+
+The rule is normative — it decides what may be added to this project — and it
+argues from concrete pairs: decompression undoes compression, the unwrapper
+undoes the wrapper, `global_to_local` undoes `local_to_global`, `trickle`
+undoes `latch`, and the playout pacer compensates for the medium. A rule that
+reasons from examples is only as good as the examples, and a renamed node
+leaves it quietly arguing from things that are not there any more.
+
+This is a documentation test, not a behaviour test: there is no behaviour to
+run. What it pins is that every node the rule names still exists, that the two
+tests it offers still name assertions the session schema accepts, and that the
+section it belongs to is still where §7 sends the reader.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+TERMINOLOGY = REPO_ROOT / "terminology.md"
+COM_PY = REPO_ROOT / "src" / "rosotacom" / "resources" / "ws" / "ros2src" / "com_py" / "com_py"
+STATUS_EVAL = REPO_ROOT / "src" / "rosotacom" / "status_eval.py"
+GENERATOR_PY = (
+    REPO_ROOT / "src" / "rosotacom" / "resources" / "ws" / "session" / "creation" / "generate_session_files.py"
+)
+
+#: The nodes §9.1 argues from, as module names in `com_py`.
+CITED_NODES = (
+    "universal_compressor",
+    "universal_decompressor",
+    "universal_ota_wrapper",
+    "universal_ota_unwrapper",
+    "local_global_frame_bridge",
+    "trickle",
+    "playout_pacer",
+)
+
+#: The processing keys §9.1's inverse pairs are stated in. A session has to
+#: still be able to declare each of them, or the pair argues from nothing.
+CITED_STAGE_KEYS = ("latch", "local_to_global", "global_to_local")
+
+#: The assertion keys §9.1 offers as its falsifiable test. They are only a
+#: test if a session may actually declare them, so each is checked against the
+#: evaluator that reads them. `vs_bag_ratio` sits under `completeness` and is
+#: named that way in the text for the same reason.
+CITED_EXPECTATIONS = ("hz", "loss_pct", "latency_ms", "completeness.vs_bag_ratio")
+
+
+#: `## 9.` and `### App Relay` are both headings, so a section has to run to
+#: the next heading of its own level or higher, not to the next heading.
+def section(title: str) -> str:
+    """The text of one `terminology.md` section, up to the next peer heading."""
+    text = TERMINOLOGY.read_text(encoding="utf-8")
+    match = re.search(
+        rf"^(#+) {re.escape(title)}\s*$",
+        text,
+        re.MULTILINE,
+    )
+    assert match is not None, f"terminology.md has no section '{title}'"
+    depth = len(match.group(1))
+    rest = text[match.end() :]
+    end = re.search(rf"^#{{1,{depth}}} ", rest, re.MULTILINE)
+    return rest[: end.start()] if end else rest
+
+
+def test_the_rule_is_where_the_stage_definition_sends_the_reader():
+    # §7 defers the ownership question rather than answering it twice.
+    assert "§9.1" in section("7. Processing and transformations")
+    assert section("9.1 Stage ownership (which transformations belong to this project)")
+
+
+def test_every_node_the_rule_argues_from_still_exists():
+    missing = [name for name in CITED_NODES if not (COM_PY / f"{name}.py").is_file()]
+
+    assert not missing, f"terminology.md §9.1 cites nodes that are gone: {missing}"
+
+
+def test_the_stage_keywords_the_rule_argues_from_are_still_session_vocabulary():
+    # The rule reasons from inverse pairs, so it breaks quietly when a session
+    # key is renamed: the prose keeps arguing from a `latch` or a
+    # `local_to_global` that no definition can declare any more.
+    body = section("9.1 Stage ownership (which transformations belong to this project)")
+    generator = GENERATOR_PY.read_text(encoding="utf-8")
+
+    for key in CITED_STAGE_KEYS:
+        assert f"`{key}`" in body, f"§9.1 no longer argues from '{key}'"
+        assert f'"{key}"' in generator, (
+            f"§9.1 argues from '{key}', which the session generator no longer knows as a processing key"
+        )
+
+
+def test_the_falsifiable_test_names_assertions_a_session_may_declare():
+    body = section("9.1 Stage ownership (which transformations belong to this project)")
+    evaluator = STATUS_EVAL.read_text(encoding="utf-8")
+
+    for key in CITED_EXPECTATIONS:
+        assert f"`{key}`" in body, f"§9.1 no longer offers '{key}'"
+        for part in key.split("."):
+            assert f'"{part}"' in evaluator, (
+                f"§9.1 offers '{key}' as an expectation, but status_eval does not know '{part}'"
+            )