reactor-runtime 3.8.0__tar.gz → 3.8.2__tar.gz

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.8.0
+Version: 3.8.2
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -19,7 +19,7 @@ Requires-Dist: numpy>=2.1
 Requires-Dist: prometheus-client>=0.26.0
 Requires-Dist: protobuf>=7.35.1
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: reactor-webrtc==0.21.0
+Requires-Dist: reactor-webrtc==0.22.1
 Requires-Dist: uvicorn>=0.49.0
 Requires-Python: >=3.12
 Project-URL: Source, https://github.com/reactor-team/reactor-runtime
@@ -124,7 +124,7 @@ class MyModel(ReactorApp):
 
 Command handlers and lifecycle hooks run between steps, never during one. A model has one method per lifecycle hook kind (`@session_started`, `@session_ended`, `@connected`, `@disconnected`, `@file_uploaded`). A subclass extends an inherited hook by overriding that method and calling `super()`; the override runs whether or not it repeats the decorator. Marking a second method with the same kind, in one class or in a subclass, fails when the class is defined, so a hook is never dropped in silence. The default `run()` is the loop that drives the three hooks, and it reports each step that runs with `complete_step()`, which is what the runtime counts a session's steps by. To write that report yourself, for example to keep extra files with the step, return a `StepCompleted(output=..., files=...)` from `process_output()` instead of the `Output`. Override `run()` to write your own loop against `emit()`, `send()`, `complete_step()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called, and your loop calls `complete_step(StepCompleted(output=...))` each time it finishes a unit of work. Do that for a loop that is not one step per emit, such as a renderer that emits several times per step or a model that must block on an input.
 
-A session can start with its setup already in hand: `POST /start_session` takes a `starting_input` of state values and commands, which the runtime applies on the normal command path before any client connects. A system client sends them, a connection the runtime opens itself, so a handler that takes `client` gets a `ClientInfo` whose `system` is true. The step loop takes its first step only once every starting command has landed, uploads included, so no step runs on the defaults the starting input replaces. In a live session the system client then leaves and the loop waits for a viewer, as it always does; a model with its own `run()` sees the system client connect like any client. A live session stays `waiting` while its starting input applies, because the system client does not occupy it, and `/events` journals the system client's `connection_opened` and `connection_closed` as `waiting -> waiting`. A session with `steps` is occupied by the system client until it ends, so it streams with no other client. The runtime ends it itself once the model has reported that many steps, with a normal stop whose close reason is "Session ended: the requested steps are complete."
+A session can start with its setup already in hand: `POST /start_session` takes a `starting_input` of state values and commands, which the runtime applies on the normal command path before any client connects. A system client sends them, a connection the runtime opens itself, so a handler that takes `client` gets a `ClientInfo` whose `system` is true. The step loop takes its first step only once every starting command has landed, uploads included, so no step runs on the defaults the starting input replaces. In a live session the system client then leaves and the loop waits for a viewer, as it always does; a model with its own `run()` sees the system client connect like any client. A live session stays `waiting` while its starting input applies, because the system client does not occupy it, and `/events` journals the system client's `connection_opened` and `connection_closed` as `waiting -> waiting`. A session with `steps` is occupied by the system client until it ends, so it streams with no other client. `steps` is a whole number from 1 to 10,000. The runtime ends it itself once the model has reported that many steps, with a normal stop whose close reason is "Session ended: the requested steps are complete." A session with `steps` has no client to correct its starting input, so a starting command the runtime cannot apply (an upload whose bytes never arrive, or arguments the contract refuses) ends it at once with the reason `start_refused` and the refusal as its close reason. If the handler of a starting command fails instead, by raising `CommandError` or any other exception, every step the model has not reported yet is recorded with the handler's message, so a session at step 3 of 4 saves steps 3 and 4 with that error, and the session ends with the reason `error`. The model keeps running and takes the next session.
 
 A model can keep each step it reports as a folder of files, turned on in `reactor.yaml`:
 
@@ -137,7 +137,7 @@ runtime:
     queue: 8
 ```
 
-Every track of the step's output becomes its own stream in one `output.mp4`, beside the extra `files` the step carried and a `result.json` that lists them. `queue` bounds how many steps may wait to be saved; a step that finds it full is not saved, so saving never holds the model up. Each step is its own encode, so this suits a model that finishes a step every few seconds rather than every frame.
+Every track of the step's output becomes its own stream in one `output.mp4`, beside the extra `files` the step carried and a `result.json` that lists them, with the measured length, frame count, frame rate, and size of each video track in its `usage`. `queue` bounds how many steps the model reports may wait to be saved; a step that finds it full is not saved, so saving never holds the model up. The steps a failed starting command records are saved past that bound, so each of them gets its folder. Each step is its own encode, so this suits a model that finishes a step every few seconds rather than every frame.
 
 When step results are on, `GET /sessions/{id}/steps` lists a session's saved folders by the session's own id; each stays readable for five minutes after it is written, after the session ends too.
 

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/README.md

@@ -97,7 +97,7 @@ class MyModel(ReactorApp):
 
 Command handlers and lifecycle hooks run between steps, never during one. A model has one method per lifecycle hook kind (`@session_started`, `@session_ended`, `@connected`, `@disconnected`, `@file_uploaded`). A subclass extends an inherited hook by overriding that method and calling `super()`; the override runs whether or not it repeats the decorator. Marking a second method with the same kind, in one class or in a subclass, fails when the class is defined, so a hook is never dropped in silence. The default `run()` is the loop that drives the three hooks, and it reports each step that runs with `complete_step()`, which is what the runtime counts a session's steps by. To write that report yourself, for example to keep extra files with the step, return a `StepCompleted(output=..., files=...)` from `process_output()` instead of the `Output`. Override `run()` to write your own loop against `emit()`, `send()`, `complete_step()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called, and your loop calls `complete_step(StepCompleted(output=...))` each time it finishes a unit of work. Do that for a loop that is not one step per emit, such as a renderer that emits several times per step or a model that must block on an input.
 
-A session can start with its setup already in hand: `POST /start_session` takes a `starting_input` of state values and commands, which the runtime applies on the normal command path before any client connects. A system client sends them, a connection the runtime opens itself, so a handler that takes `client` gets a `ClientInfo` whose `system` is true. The step loop takes its first step only once every starting command has landed, uploads included, so no step runs on the defaults the starting input replaces. In a live session the system client then leaves and the loop waits for a viewer, as it always does; a model with its own `run()` sees the system client connect like any client. A live session stays `waiting` while its starting input applies, because the system client does not occupy it, and `/events` journals the system client's `connection_opened` and `connection_closed` as `waiting -> waiting`. A session with `steps` is occupied by the system client until it ends, so it streams with no other client. The runtime ends it itself once the model has reported that many steps, with a normal stop whose close reason is "Session ended: the requested steps are complete."
+A session can start with its setup already in hand: `POST /start_session` takes a `starting_input` of state values and commands, which the runtime applies on the normal command path before any client connects. A system client sends them, a connection the runtime opens itself, so a handler that takes `client` gets a `ClientInfo` whose `system` is true. The step loop takes its first step only once every starting command has landed, uploads included, so no step runs on the defaults the starting input replaces. In a live session the system client then leaves and the loop waits for a viewer, as it always does; a model with its own `run()` sees the system client connect like any client. A live session stays `waiting` while its starting input applies, because the system client does not occupy it, and `/events` journals the system client's `connection_opened` and `connection_closed` as `waiting -> waiting`. A session with `steps` is occupied by the system client until it ends, so it streams with no other client. `steps` is a whole number from 1 to 10,000. The runtime ends it itself once the model has reported that many steps, with a normal stop whose close reason is "Session ended: the requested steps are complete." A session with `steps` has no client to correct its starting input, so a starting command the runtime cannot apply (an upload whose bytes never arrive, or arguments the contract refuses) ends it at once with the reason `start_refused` and the refusal as its close reason. If the handler of a starting command fails instead, by raising `CommandError` or any other exception, every step the model has not reported yet is recorded with the handler's message, so a session at step 3 of 4 saves steps 3 and 4 with that error, and the session ends with the reason `error`. The model keeps running and takes the next session.
 
 A model can keep each step it reports as a folder of files, turned on in `reactor.yaml`:
 
@@ -110,7 +110,7 @@ runtime:
     queue: 8
 ```
 
-Every track of the step's output becomes its own stream in one `output.mp4`, beside the extra `files` the step carried and a `result.json` that lists them. `queue` bounds how many steps may wait to be saved; a step that finds it full is not saved, so saving never holds the model up. Each step is its own encode, so this suits a model that finishes a step every few seconds rather than every frame.
+Every track of the step's output becomes its own stream in one `output.mp4`, beside the extra `files` the step carried and a `result.json` that lists them, with the measured length, frame count, frame rate, and size of each video track in its `usage`. `queue` bounds how many steps the model reports may wait to be saved; a step that finds it full is not saved, so saving never holds the model up. The steps a failed starting command records are saved past that bound, so each of them gets its folder. Each step is its own encode, so this suits a model that finishes a step every few seconds rather than every frame.
 
 When step results are on, `GET /sessions/{id}/steps` lists a session's saved folders by the session's own id; each stays readable for five minutes after it is written, after the session ends too.
 

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/pyproject.toml

@@ -10,7 +10,7 @@ module-name = [
 namespace = true
 
 [tool.reactor-wire]
-version = "1.20260929.8"
+version = "1.20261013.10"
 
 [tool.ruff]
 line-length = 100
@@ -95,7 +95,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.8.0"
+version = "3.8.2"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -119,7 +119,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.21.0",
+    "reactor-webrtc==0.22.1",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/pyproject.toml.orig

@@ -16,11 +16,11 @@ namespace = true
 # gates the pin against proto/, so a release cannot ship a schema older than the
 # sources it was built from.
 [tool.reactor-wire]
-version = "1.20260929.8"
+version = "1.20261013.10"
 
 [project]
 name = "reactor-runtime"
-version = "3.8.0"
+version = "3.8.2"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -42,7 +42,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.21.0",
+    "reactor-webrtc==0.22.1",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/core/__init__.py

@@ -34,7 +34,12 @@ from reactor_runtime.core.session import (
     Transition,
 )
 from reactor_runtime.core.stats import TransportReading, TransportTrackReading
-from reactor_runtime.core.transport import Connection, ConnectionSink, TransportStatsSource
+from reactor_runtime.core.transport import (
+    Connection,
+    ConnectionSink,
+    FrameStageSource,
+    TransportStatsSource,
+)
 from reactor_runtime.core.typespec import TypeSpec
 from reactor_runtime.core.values import (
     ClientConnectionStat,
@@ -45,6 +50,7 @@ from reactor_runtime.core.values import (
     CompletedStep,
     ConnectionCapabilities,
     ConnId,
+    FrameStage,
     Health,
     HealthStatus,
     InputFrame,
@@ -76,6 +82,8 @@ __all__ = [
     "EndReason",
     "FieldInfo",
     "FileUploaded",
+    "FrameStage",
+    "FrameStageSource",
     "Health",
     "HealthStatus",
     "InputField",

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/core/model.py

@@ -189,13 +189,19 @@ def _build_command(cls: type[Command]) -> None:
 
 
 class EndReason(StrEnum):
-    """Why a session ended."""
+    """Why a session ended.
+
+    ``START_REFUSED`` ends a session with a step count whose starting input
+    cannot be applied: a starting command names an upload whose bytes never
+    arrive, or the contract refuses its arguments.
+    """
 
     STOPPED = "stopped"
     TIMED_OUT = "timed_out"
     EVICTED = "evicted"
     MODERATED = "moderated"
     ERROR = "error"
+    START_REFUSED = "start_refused"
 
 
 @dataclass(frozen=True)

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/core/stats.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 
-from reactor_runtime.core.values import ClientTrackDirection, TrackKind
+from reactor_runtime.core.values import ClientTrackDirection, FrameStage, TrackKind
 
 
 @dataclass(frozen=True)
@@ -32,6 +32,8 @@ class TransportTrackReading:
             ``"packets_lost"``, ``"frames_per_second"``), and a measurement the
             transport has no value for is left out rather than reported as
             zero.
+        frame_stages: Where the track's frames spent their time on this side
+            of the wire since the previous reading, stage by stage.
     """
 
     track_name: str
@@ -39,6 +41,7 @@ class TransportTrackReading:
     direction: ClientTrackDirection
     codec: str = ""
     metrics: Mapping[str, float] = field(default_factory=dict)
+    frame_stages: tuple[FrameStage, ...] = ()
 
 
 @dataclass(frozen=True)

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/core/transport.py

@@ -4,13 +4,14 @@ The two structural protocols that form the seam between a transport and the
 runner, pointing opposite ways. ``Connection`` carries commands down to one
 client; ``ConnectionSink`` carries facts up from the transport. Both are
 ``Protocol``s, so a transport author or a test fake conforms by shape and
-signaling never reaches the runner. ``TransportStatsSource`` is an optional
-capability a connection adds when its transport measures its wire.
+signaling never reaches the runner. ``TransportStatsSource`` and
+``FrameStageSource`` are optional capabilities a connection adds when its
+transport measures its wire.
 """
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Collection, Mapping
 from typing import Protocol, runtime_checkable
 
 from reactor_runtime.core.stats import TransportReading
@@ -18,6 +19,7 @@ from reactor_runtime.core.values import (
     ClientStatsBatch,
     ConnectionCapabilities,
     ConnId,
+    FrameStage,
     InputFrame,
     MediaChunk,
 )
@@ -118,6 +120,24 @@ class TransportStatsSource(Protocol):
         """
 
 
+@runtime_checkable
+class FrameStageSource(Protocol):
+    """A connection whose transport times each frame's stages on its side of the wire.
+
+    Optional, beside :class:`TransportStatsSource`, and checked for the same
+    way. A track's times add up until they are taken, so each take covers the
+    window since that track's previous one.
+    """
+
+    def take_frame_stages(self, tracks: Collection[str]) -> Mapping[str, tuple[FrameStage, ...]]:
+        """Return the stage times of *tracks* since their previous take, and start them again.
+
+        Keyed by track name. A track with no frames in its window is left out,
+        and so is a stage with no frames in it. Tracks not named keep their
+        times for a later take.
+        """
+
+
 @runtime_checkable
 class ConnectionSink(Protocol):
     """The transport-to-runner upward channel — the facts-up half.

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/core/values.py

@@ -44,6 +44,29 @@ class CommandFailure:
     message: str
 
 
+@dataclass(frozen=True)
+class FrameStage:
+    """The time a track's frames spent in one stage of their trip, over one window.
+
+    The stages cover the transport between the client's app and the model:
+    ``submit``, ``encode_wait``, ``encode``, ``packetize``, ``pacer``,
+    ``jitter_buffer``, ``decode``, ``delivery``, ``output_pacing`` and
+    ``output_queue``, in the order a frame goes through them. Each side
+    reports the stages it can see. The set grows, so a reader ignores a name
+    it does not know.
+
+    Attributes:
+        name: The stage.
+        total_ms: The time all *frames* frames spent in the stage together,
+            so the average per frame is ``total_ms / frames``.
+        frames: How many frames the window counted in the stage.
+    """
+
+    name: str
+    total_ms: float
+    frames: int
+
+
 @dataclass(frozen=True)
 class ClientTrackStat:
     """One WebRTC quality reading a client took for one of its tracks.
@@ -80,6 +103,8 @@ class ClientTrackStat:
             readings with different totals cannot be re-aggregated correctly
             afterward; a raw count can always be summed and divided once, at
             query time.
+        frame_stages: Where the track's frames spent their time since the
+            client's previous batch, stage by stage.
     """
 
     timestamp: int
@@ -89,6 +114,7 @@ class ClientTrackStat:
     codec: str
     paused: bool
     metrics: Mapping[str, float]
+    frame_stages: tuple[FrameStage, ...] = ()
 
 
 @dataclass(frozen=True)

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/http/routes.py

@@ -18,6 +18,7 @@ from pydantic import BaseModel, Field
 
 from reactor_runtime.core import Health, HealthStatus, RuntimeState, SessionState
 from reactor_runtime.http.events import format_sse
+from reactor_runtime.http.step_usage import StepUsage
 from reactor_runtime.metrics import CONTENT_TYPE as METRICS_CONTENT_TYPE
 from reactor_runtime.metrics import RuntimeMetrics
 from reactor_runtime.recording import ClipManifest, ClipSessionGoneError, Pending
@@ -380,6 +381,9 @@ class StepResult(BaseModel):
     step: int
     session_id: str
     files: list[StepFile] = Field(description="The files beside result.json.")
+    usage: list[StepUsage] = Field(
+        description="One entry per video track the step wrote; empty when it wrote none."
+    )
     messages: list[StepMessage] = Field(
         description="The messages the model broadcast since the step before."
     )

reactor_runtime-3.8.2/src/reactor_runtime/http/step_usage.py

@@ -0,0 +1,30 @@
+"""The HTTP shape of what a saved step delivered: the ``usage`` entries of ``result.json``.
+
+Each kind of output a step can deliver has its own model here, tagged by a
+``kind`` literal, and :data:`StepUsage` is the type of one entry. A new kind
+adds its model to this module and joins :data:`StepUsage`, which then becomes
+a union discriminated on ``kind``, so the route models never change.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class StepVideoUsage(BaseModel):
+    """The measured facts of one video track the step wrote, as the file holds it."""
+
+    kind: Literal["video"]
+    track: str = Field(description="The output track the stream holds.")
+    file: str = Field(description="The file the stream is in.")
+    duration_s: float = Field(description="How long the stream plays, in seconds.")
+    frames: int = Field(description="How many frames the stream holds.")
+    fps: float = Field(description="The rate the stream plays at, in frames per second.")
+    width: int = Field(description="The stream's width in pixels.")
+    height: int = Field(description="The stream's height in pixels.")
+
+
+StepUsage = StepVideoUsage
+"""One ``usage`` entry of a step's ``result.json``."""

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/metrics/session.py

@@ -29,7 +29,7 @@ def _reason_label(detail: Mapping[str, Any]) -> str:
 
     The runtime authors every reason, and a move that names none is a plain stop —
     the same reading the runner's own dispatch takes. The type guard holds the
-    label to the five :class:`EndReason` values whatever a caller puts in the
+    label to the :class:`EndReason` values whatever a caller puts in the
     detail, because one unbounded label value costs a series forever.
     """
     reason = detail.get("reason", EndReason.STOPPED)

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/runner/client_stats.py

@@ -12,16 +12,17 @@ from __future__ import annotations
 
 import math
 import time
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from typing import Any
 
-from reactor_runtime.core import ClientStatsBatch, ConnId
+from reactor_runtime.core import ClientStatsBatch, ConnId, FrameStage
 
 # The SDK sends a batch every few seconds, with a few tracks and a few dozen
 # metrics each; these limits are far above that.
 MIN_INTERVAL_SECONDS = 1.0
 MAX_TRACKS = 32
 MAX_METRICS = 64
+MAX_FRAME_STAGES = 32
 MAX_NAME_LENGTH = 128
 
 
@@ -70,7 +71,10 @@ def fits(batch: ClientStatsBatch) -> bool:
         readings.append(batch.connection_stat.metrics)
     if any(len(metrics) > MAX_METRICS for metrics in readings):
         return False
+    if any(len(stat.frame_stages) > MAX_FRAME_STAGES for stat in batch.track_stats):
+        return False
     names = [name for metrics in readings for name in metrics]
+    names += [stage.name for stat in batch.track_stats for stage in stat.frame_stages]
     names += [field for stat in batch.track_stats for field in (stat.track_name, stat.codec)]
     return all(len(name) <= MAX_NAME_LENGTH for name in names)
 
@@ -91,6 +95,7 @@ def to_detail(batch: ClientStatsBatch) -> dict[str, Any]:
                 "codec": stat.codec,
                 "paused": stat.paused,
                 "metrics": _finite(stat.metrics),
+                "frame_stages": frame_stages_detail(stat.frame_stages),
             }
             for stat in batch.track_stats
         ],
@@ -105,6 +110,20 @@ def to_detail(batch: ClientStatsBatch) -> dict[str, Any]:
     }
 
 
+def frame_stages_detail(stages: Iterable[FrameStage]) -> list[dict[str, Any]]:
+    """Shape a track's stage times for a fact's detail.
+
+    A stage with no name or no frames has no average, and a negative time or
+    one JSON cannot carry is no measurement, so all of them are left out. The
+    runtime's own stages follow the same rule when they are timed.
+    """
+    return [
+        {"name": stage.name, "total_ms": stage.total_ms, "frames": stage.frames}
+        for stage in stages
+        if stage.name and stage.frames > 0 and math.isfinite(stage.total_ms) and stage.total_ms >= 0
+    ]
+
+
 def _finite(metrics: Mapping[str, float]) -> dict[str, float]:
     """Keep the metric values JSON can carry: finite numbers, not NaN or infinity."""
     return {key: value for key, value in metrics.items() if math.isfinite(value)}

{reactor_runtime-3.8.0 → reactor_runtime-3.8.2}/src/reactor_runtime/runner/connection_manager.py

@@ -41,11 +41,13 @@ replaced rather than edited.
 from __future__ import annotations
 
 import random
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import replace
 
 from reactor_runtime.core import (
     Connection,
     ConnId,
+    FrameStageSource,
     MediaChunk,
     SessionEvent,
     TransportReading,
@@ -146,7 +148,7 @@ class ConnectionManager:
 
         A connection whose transport has not taken a reading yet, or does not
         measure its wire (it is not a :class:`TransportStatsSource`), is left
-        out.
+        out. Reading them changes nothing, so any number of callers can.
         """
         return [
             (cid, reading)
@@ -155,6 +157,34 @@ class ConnectionManager:
             and (reading := conn.latest_reading) is not None
         ]
 
+    def take_frame_stages(
+        self, readings: Iterable[tuple[ConnId, TransportReading]]
+    ) -> list[tuple[ConnId, TransportReading]]:
+        """Add each connection's stage times since the previous take to its *readings*.
+
+        For a connection that times its frames (a :class:`FrameStageSource`),
+        each track in its reading gets the stage times the connection held for
+        it, and those are taken: the next call gets only what was timed after
+        this one, so the runner calls this once per report. Stages of a track
+        the reading does not carry yet stay with the connection until a
+        reading does. A connection with no reading here keeps all its stages.
+        """
+        out: list[tuple[ConnId, TransportReading]] = []
+        for cid, reading in readings:
+            conn = self._by_id.get(cid)
+            if isinstance(conn, FrameStageSource) and reading.tracks:
+                stages = conn.take_frame_stages([t.track_name for t in reading.tracks])
+                if stages:
+                    reading = replace(
+                        reading,
+                        tracks=tuple(
+                            replace(track, frame_stages=stages.get(track.track_name, ()))
+                            for track in reading.tracks
+                        ),
+                    )
+            out.append((cid, reading))
+        return out
+
     def new_conn_id(self) -> ConnId:
         """Mint a fresh random connection id, unique within the session.