reactor-runtime 2.7.6__tar.gz → 2.7.7__tar.gz

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.7.6
+Version: 2.7.7
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.7.6"
+version = "2.7.7"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/src/reactor_runtime/interface/internal/output_buffer.py

@@ -105,25 +105,9 @@ def split_batch(bundle: MediaBundle) -> List[MediaBundle]:
 class _FlushMarker:
     """Sentinel placed in :class:`OutputBuffer`'s queue by :meth:`flush`.
 
-    Carries no payload. When the emission loop dequeues an instance, it
-    resets ``_last_emitted`` *in-thread* and falls through to this
-    tick's empty-queue fallback (which dispatches a fresh
-    ``_create_black_bundle()`` with ``duplicate=True``).
-
-    The point of routing the session-boundary reset through the queue
-    rather than writing ``_last_emitted = None`` directly from
-    :meth:`flush` is to make the reset atomic with respect to the
-    emission thread: only the emission thread reads or writes
-    ``_last_emitted``, so the loop can never observe a half-applied
-    "queue drained but cached frame not yet cleared" state. Down-stream
-    callbacks already drop ``duplicate=True`` bundles (the wire
-    callback in ``_send_out_app_bundle_sync`` short-circuits, and the
-    :class:`~reactor_runtime.recording.session_recorder.SessionRecorder`
-    skips them when ``skip_leading_black`` is on and
-    ``recording_started`` is still False), so no stale frame would
-    reach the client or recording even without this guarantee — but
-    closing the race architecturally is cheaper than re-deriving that
-    safety argument for every callback added in the future.
+    Consumed by the emission thread, which resets ``_last_emitted`` and
+    dispatches a fresh black bundle with ``is_fresh_black=True``.  Doing
+    the reset in-thread keeps it atomic with the per-tick state read.
     """
 
 
@@ -152,13 +136,11 @@ class OutputBuffer:
         # Ordered list of per-tick observers.  Callbacks fire in
         # registration order on every emission tick; an exception in
         # one callback is logged and does not block the others.
-        self._callbacks: List[Callable[[MediaBundle, bool], None]] = []
+        self._callbacks: List[Callable[[MediaBundle, bool, bool], None]] = []
         self._callbacks_lock: threading.Lock = threading.Lock()
 
-        # Queue items are normally MediaBundle, but flush() also puts a
-        # _FlushMarker sentinel here. We type the queue as ``object`` so
-        # both shapes are valid; the emission loop discriminates with
-        # ``isinstance``.
+        # Holds MediaBundle plus the _FlushMarker sentinel; the
+        # emission loop discriminates by isinstance.
         self._q: queue.Queue[object] = queue.Queue(maxsize=queue_depth)
 
         # FPS control — store both rate and period to avoid 1/fps on every tick
@@ -182,29 +164,18 @@ class OutputBuffer:
     # Callbacks
     # ------------------------------------------------------------------
 
-    def add_callback(self, fn: Callable[[MediaBundle, bool], None]) -> None:
-        """Register a per-tick callback.
+    def add_callback(self, fn: Callable[[MediaBundle, bool, bool], None]) -> None:
+        """Register a per-tick callback ``(bundle, duplicate, is_fresh_black)``.
 
-        Idempotent: registering the same ``fn`` twice leaves the
-        callback list with a single entry. This mirrors
-        :meth:`remove_callback` which has always been a no-op on
-        already-unregistered functions — callers shouldn't have to
-        track registration state.
-
-        The callback receives ``(bundle, duplicate)`` on every emission
-        tick.  Callbacks fire in registration order and are isolated
-        from each other: an exception raised by one is logged and the
-        remaining callbacks still fire.
+        Idempotent — re-registering the same ``fn`` is a no-op.
+        Callbacks fire in registration order with exceptions isolated.
         """
         with self._callbacks_lock:
             if fn not in self._callbacks:
                 self._callbacks.append(fn)
 
-    def remove_callback(self, fn: Callable[[MediaBundle, bool], None]) -> None:
-        """Deregister a previously added callback.
-
-        No-op if *fn* was never registered.
-        """
+    def remove_callback(self, fn: Callable[[MediaBundle, bool, bool], None]) -> None:
+        """Deregister a previously added callback (no-op if not registered)."""
         with self._callbacks_lock:
             try:
                 self._callbacks.remove(fn)
@@ -320,27 +291,30 @@ class OutputBuffer:
     # Stage 3: Emission loop
     # ------------------------------------------------------------------
 
-    def _dispatch(self, bundle: MediaBundle, duplicate: bool) -> None:
+    def _dispatch(
+        self,
+        bundle: MediaBundle,
+        duplicate: bool,
+        *,
+        is_fresh_black: bool = False,
+    ) -> None:
         """Fire every registered callback in order with error isolation.
 
-        We snapshot the callback list under the lock so callbacks that
-        register/deregister siblings during dispatch don't perturb the
-        current tick.  Each callback is wrapped so an exception in one
-        does not block the others.
+        Callbacks receive ``(bundle, duplicate, is_fresh_black)``.
+        ``is_fresh_black`` is ``True`` only on the synthesised black
+        the sentinel path emits at session boundaries; callbacks
+        choose how to interpret that separately from ``duplicate``.
+        Exceptions in one callback are logged and don't block the
+        rest.
         """
         with self._callbacks_lock:
             callbacks = list(self._callbacks)
         for fn in callbacks:
             try:
-                fn(bundle, duplicate)
+                fn(bundle, duplicate, is_fresh_black)
             except Exception as ex:
-                # ``logger.exception`` already attaches sys.exc_info()'s
-                # traceback; we also surface the type + message as
-                # structured fields so log queries on ``exc_type`` /
-                # ``exc_msg`` / ``callback`` work without traceback
-                # parsing. Without these explicit fields a silent
-                # malfunction in a downstream callback looks like
-                # "feature X didn't fire" with no obvious cause.
+                # Structured fields so log queries on exc_type /
+                # exc_msg / callback work without traceback parsing.
                 logger.exception(
                     "OutputBuffer callback raised; continuing with remaining callbacks",
                     callback=repr(fn),
@@ -361,19 +335,24 @@ class OutputBuffer:
                     item = None
 
                 bundle: Optional[MediaBundle] = None
+                sentinel_consumed = False
                 if isinstance(item, _FlushMarker):
-                    # Session-boundary reset, processed in the emission
-                    # thread so there is no cross-thread race with
-                    # flush(): clear the cached frame and fall through
-                    # to the empty-queue fallback below, which
-                    # dispatches duplicate=True black. mark_first_real_frame()
-                    # is gated on duplicate=False, so the recorder's
-                    # latch (REA-2323 / #2325) stays unset.
                     self._last_emitted = None
+                    sentinel_consumed = True
                 elif isinstance(item, MediaBundle):
                     bundle = item
 
-                if bundle is not None:
+                if sentinel_consumed:
+                    # Session-boundary black: tagged so the wire
+                    # forwards it (otherwise the client would stay
+                    # frozen on the previous frame), the recorder
+                    # ignores it.
+                    self._dispatch(
+                        self._create_black_bundle(),
+                        True,
+                        is_fresh_black=True,
+                    )
+                elif bundle is not None:
                     vtracks = bundle.get_tracks_by_kind(TrackKind.VIDEO)
                     if vtracks:
                         vd = vtracks[0].data
@@ -511,36 +490,16 @@ class OutputBuffer:
     def flush(self) -> None:
         """Drop pending bundles and request a session-boundary reset.
 
-        The reset of ``_last_emitted`` is performed by the emission
-        thread when it dequeues the :class:`_FlushMarker` sentinel,
-        making the operation race-free with the per-tick
-        "what do I emit?" decision in :meth:`_emission_loop`. After the
-        sentinel is consumed, the next emission tick synthesises
-        ``_create_black_bundle()`` with ``duplicate=True`` — the
-        correct pre-roll behaviour for a session boundary:
-
-        * the wire callback (``_send_out_app_bundle_sync``) drops
-          ``duplicate=True`` outright;
-        * the recorder's ``mark_first_real_frame()`` latch is not
-          tripped (REA-2323 / #2325), so the recording timeline only
-          starts at the next real model frame.
-
-        Safe to call from any thread; in practice ``flush()`` is
-        called from the model thread (``model-run``), the same thread
-        that calls :meth:`submit`, so there is no submit/flush race
-        on the producer side either.
+        The emission thread performs the actual reset of
+        ``_last_emitted`` when it dequeues the sentinel.  Then the
+        next tick emits a fresh black bundle tagged ``is_fresh_black``
+        — forwarded by the wire, ignored by the recorder.
         """
         self._drain_queue()
         try:
             self._q.put_nowait(_FLUSH_MARKER)
         except queue.Full:
-            # Unreachable in practice: the queue is bounded and the
-            # only producer (submit) runs on the same thread as
-            # flush, so nothing can refill the queue between drain
-            # and put. Log loudly if it ever happens and continue —
-            # the next real frame from the new session will set
-            # _last_emitted correctly even if the sentinel never
-            # lands.
+            # Same thread as submit(), so unreachable in practice.
             logger.warning(
                 "OutputBuffer.flush: queue full immediately after drain; "
                 "reset sentinel dropped"

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/src/reactor_runtime/recording/session_recorder.py

@@ -250,10 +250,22 @@ class SessionRecorder:
     # OutputBuffer integration
     # ------------------------------------------------------------------
 
-    def _on_bundle_sync(self, bundle: MediaBundle, duplicate: bool) -> None:
-        """Enqueue a bundle for the feed worker; non-blocking."""
+    def _on_bundle_sync(
+        self,
+        bundle: MediaBundle,
+        duplicate: bool,
+        is_fresh_black: bool = False,
+    ) -> None:
+        """Enqueue a bundle for the feed worker; non-blocking.
+
+        Session-boundary synthesised black (``is_fresh_black``) is not
+        real model output and is invisible to the recording timeline:
+        no feed-queue write, no ``mark_first_real_frame`` consideration.
+        """
         if self._disabled or not self._started:
             return
+        if is_fresh_black:
+            return
         now = time.monotonic()
         if duplicate:
             if self._config.skip_leading_black and not self._markers.recording_started:

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/src/reactor_runtime/runtime_api.py

@@ -350,22 +350,19 @@ class Runtime(ModelStateMachine, ABC):
             logger.warning("Failed to send app message", error=e)
 
     def _send_out_app_bundle_sync(
-        self, media_bundle: MediaBundle, duplicate: bool
+        self,
+        media_bundle: MediaBundle,
+        duplicate: bool,
+        is_fresh_black: bool = False,
     ) -> None:
-        """Callback from the :class:`FrameBuffer` emission loop.
-
-        Silently fails if the event loop is closed (expected during shutdown).
-
-        When *duplicate* is ``True`` the bundle is a re-emission of the
-        last frame (queue was empty, video-only).  We skip forwarding
-        entirely: the video track already serves the last pushed frame,
-        and pushing the same frame again only wastes event-loop time.
+        """OutputBuffer callback — forward real frames + session-boundary black.
 
-        Args:
-            media_bundle: The :class:`MediaBundle` to send.
-            duplicate: True if this is a re-emission of the last frame.
+        Drops keepalive duplicates (the wire track already shows that
+        frame) but forwards ``is_fresh_black`` bundles so the client
+        transitions off the previous session's last frame on flush.
+        Silently fails if the event loop is closed (shutdown).
         """
-        if duplicate:
+        if duplicate and not is_fresh_black:
             return
         if self.loop.is_closed():
             return

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/src/reactor_runtime/runtimes/headless/headless_runtime.py

@@ -70,19 +70,26 @@ class HeadlessRuntime(Runtime):
     # Runtime API implementation - MODEL -> CLIENT (stdout)
     # ===============================
 
-    def _send_out_app_bundle_sync(self, media_bundle, duplicate: bool) -> None:
-        """Override base-class sync wrapper to forward duplicates.
-
-        The base :class:`Runtime` drops duplicates because re-sending
-        the same frame over WebRTC is wasteful.  The headless runtime
-        needs to see them so that ``send_out_app_bundle`` can count
-        skipped duplicates for the ``ignore_duplicates`` feature.
+    def _send_out_app_bundle_sync(
+        self,
+        media_bundle,
+        duplicate: bool,
+        is_fresh_black: bool = False,
+    ) -> None:
+        """Forward every bundle to :meth:`send_out_app_bundle`.
+
+        Unlike the base class, headless does not drop duplicates here
+        — the async path counts them for the ``ignore_duplicates``
+        feature.  Silently fails if the event loop is closed.
         """
         if self.loop.is_closed():
             return
         try:
             asyncio.run_coroutine_threadsafe(
-                self.send_out_app_bundle(media_bundle, duplicate), self.loop
+                self.send_out_app_bundle(
+                    media_bundle, duplicate, is_fresh_black=is_fresh_black
+                ),
+                self.loop,
             )
         except RuntimeError:
             pass
@@ -105,19 +112,30 @@ class HeadlessRuntime(Runtime):
         output = json.dumps(data, indent=2)
         print(f"\n[RUNTIME] {output}", flush=True)
 
-    async def send_out_app_bundle(self, media_bundle, duplicate: bool) -> None:
-        """
-        Handle an output media bundle from the model.
-        Extracts the video frame and writes it as a PNG file.
-
-        Args:
-            media_bundle: A :class:`MediaBundle` (video track extracted).
-            duplicate: True if this is a re-emission of the last frame.
+    async def send_out_app_bundle(
+        self,
+        media_bundle,
+        duplicate: bool,
+        *,
+        is_fresh_black: bool = False,
+    ) -> None:
+        """Extract the video frame from ``media_bundle`` and write as PNG.
+
+        Skips ``is_fresh_black`` bundles (synthesised session-boundary
+        black, not model output) and — when ``ignore_duplicates`` is
+        set — ``duplicate`` keepalives.
         """
         if self.file_path is None:
             return
 
-        # Skip duplicate frames (re-emissions from the frame buffer when it's empty)
+        if is_fresh_black:
+            self._duplicates_skipped += 1
+            logger.debug(
+                "Skipped fresh-black session-boundary frame",
+                total_skipped=self._duplicates_skipped,
+            )
+            return
+
         if self.config.ignore_duplicates and duplicate:
             self._duplicates_skipped += 1
             logger.debug(

{reactor_runtime-2.7.6 → reactor_runtime-2.7.7}/src/reactor_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.7.6
+Version: 2.7.7
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9