Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

31.0 KB
Raw Blame
"""The emit layer above the socket transport: who receives, and what survives.

Main's ``web/services/socket_service.py`` has no successor file on this
branch -- the Flask ``SocketIOService`` object was replaced by module-level
functions in ``web/services/socketio_asgi.py`` plus two thin object-shaped
adapters (``research_service._SocketEmitter`` and
``benchmarks/web_api/benchmark_service.SocketIOService``). This file covers
that emit surface: the sync wrappers a background research thread actually
calls, and what happens to a payload between that call and the wire.

Four properties, none of which is pinned elsewhere:

1. **A roomless emit is a broadcast to every logged-in user.**
   ``emit_socket_event(event, data)`` defaults ``room=None``, and
   ``_async_emit`` then calls ``sio.emit(event, data)`` with no room at all.
   python-socketio resolves that to ``manager.get_participants(namespace,
   None)``, and the ``None`` room bucket is where ``BaseManager.connect``
   files *every* sid -- the server's own log line for it reads "emitting
   event X to all". So the roomless path is not "the default room", it is
   the whole namespace, across users. ``TestWhoCanReceiveARoomlessEmit``
   proves that end to end against the real ``AsyncServer`` and its real
   manager, then pins the reachability answer by AST: the only caller of
   ``emit_socket_event`` anywhere in ``src`` is
   ``SocketIOService.emit_to_room``, and ``emit_to_room`` has no callers at
   all. The broadcast is dead code today; the guard turns the first new
   caller into a failing test instead of a silent cross-user leak.

2. **The sync seam is total.** Every wrapper hands its real work to
   uvicorn's loop with ``run_coroutine_threadsafe`` and discards the Future.
   Research workers therefore treat these calls as infallible -- one call
   site (``_save_chat_message_and_context``'s final ``response_chunk``) has
   no ``try`` around it at all, so a raise there would abort the chat-persist
   path rather than merely losing a frame. ``TestTheSyncSeamIsTotal`` drives
   the degraded states a worker can actually meet and shows none of them
   reaches the calling thread -- including the one that reports success and
   delivers nothing (``_lock`` still ``None``).

3. **The loop going away is not observable from the calling thread.**
   ``TestTheLoopIsGoneAtShutdown`` covers both halves: the stopped loop that
   ``_get_main_loop``/``is_running`` catches before scheduling, and the
   check-then-schedule race it cannot catch, where the wrapper returns
   ``True`` and the event is stranded on a loop that will never run it.

4. **Delivery order is scheduling order, and nothing more.** The completion
   path depends on it (``_sio_emit(final)`` then ``_sio_remove``, back to
   back on one thread). But progress lines for a single research are
   scheduled from more than one thread -- the worker's own
   ``progress_callback``, and ``frontend_progress_sink`` firing on whichever
   thread logged, including the parallel-search workers that inherit the
   research context via ``thread_context``'s ContextVar. Nothing in this
   layer carries a sequence number or reorders, so a progress line scheduled
   after the terminal event is delivered after it.
   ``TestDeliveryOrderIsSchedulingOrderOnly`` pins both directions.

Plus ``TestThePayloadCrossesTheSeamByReference``: the payload dict is not
copied, and it is read on the loop thread after the caller has returned. No
current caller mutates one (they all build a fresh dict per emit), so this
pins a property rather than reporting a live bug.

Deliberately NOT re-litigated -- already pinned, do not duplicate:

* the discarded-Future asymmetry, ``_async_emit`` transport-failure
  containment, and the ``enable_logging`` ContextVar crossing the seam --
  ``test_socketio_asgi_contracts.py``
* reconnect/resubscribe, the stale-sid window, teardown landing mid-fanout,
  and the ``workers=1`` constraint -- ``test_socketio_connection_semantics.py``
* ``(owner, research_id)`` keying and the fail-closed unknown owner --
  ``test_subscription_owner_scoping.py``
* ``emit_to_user`` sid selection and its no-loop branches --
  ``test_socketio_asgi_user_scoping.py``
* the connect/subscribe auth and session-revocation gates --
  ``test_socketio_handshake_auth.py``, ``test_socket_connect_session_gate.py``,
  ``tests/security/test_socket_ownership_edges_fastapi.py``
* ``frontend_progress_sink``'s payload shape, truncation and owner
  resolution -- ``tests/utilities/test_log_utils*.py``
* the lifespan ordering of ``set_main_loop`` before ``init_lock`` --
  ``tests/web/test_lifespan_startup_shutdown.py``

No wall-clock sleeps: every wait is either a captured
``concurrent.futures.Future`` or a ``threading.Event`` handshake.
"""

import ast
import asyncio
import concurrent.futures
import contextlib
import copy
import functools
import threading
from pathlib import Path
from unittest.mock import patch

import pytest

from local_deep_research.web.services import socketio_asgi as sio_mod

OWNER = "emit_contracts_owner"
OTHER = "emit_contracts_other"
RID = "emit-contracts-research"
SID = "sid-owner-tab-1"


# ---------------------------------------------------------------------------
# Source scanning (no imports -- the production modules are parsed, not run)
# ---------------------------------------------------------------------------

# ``socketio_asgi.py`` lives at <pkg>/web/services/, so parents[2] is the
# installed package root whichever layout the suite is running against.
_PKG_ROOT = Path(sio_mod.__file__).resolve().parents[2]


class _CallSites(ast.NodeVisitor):
    """Record every call to a named function, with its enclosing qualname."""

    def __init__(self, wanted: set[str]):
        self.wanted = wanted
        self.found: list[tuple[str, int]] = []  # (qualname, lineno)
        self._scope: list[str] = []

    def visit_ClassDef(self, node):
        self._scope.append(node.name)
        self.generic_visit(node)
        self._scope.pop()

    def visit_FunctionDef(self, node):
        self._scope.append(node.name)
        self.generic_visit(node)
        self._scope.pop()

    visit_AsyncFunctionDef = visit_FunctionDef

    def visit_Call(self, node):
        func = node.func
        name = None
        if isinstance(func, ast.Name):
            name = func.id
        elif isinstance(func, ast.Attribute):
            name = func.attr
        if name in self.wanted:
            self.found.append((".".join(self._scope), node.lineno))
        self.generic_visit(node)


@functools.lru_cache(maxsize=8)
def _call_sites(*names: str) -> tuple[tuple[str, str, int], ...]:
    """(relative path, enclosing qualname, lineno) for every call to ``names``
    across the whole production package."""
    out: list[tuple[str, str, int]] = []
    for path in sorted(_PKG_ROOT.rglob("*.py")):
        try:
            tree = ast.parse(path.read_text(encoding="utf-8"))
        except (SyntaxError, UnicodeDecodeError):  # pragma: no cover
            continue
        visitor = _CallSites(set(names))
        visitor.visit(tree)
        rel = path.relative_to(_PKG_ROOT).as_posix()
        out.extend((rel, qual, line) for qual, line in visitor.found)
    return tuple(out)


def _guarded_line_spans(tree: ast.AST) -> list[tuple[int, int]]:
    """Line spans covered by a ``try:`` BODY (handlers/finally excluded --
    a raise there is not caught by that statement)."""
    spans = []
    for node in ast.walk(tree):
        if isinstance(node, ast.Try) and node.body:
            spans.append(
                (
                    min(stmt.lineno for stmt in node.body),
                    max(stmt.end_lineno or stmt.lineno for stmt in node.body),
                )
            )
    return spans


# ---------------------------------------------------------------------------
# Loop / state fixtures
# ---------------------------------------------------------------------------


def _start_loop_thread():
    loop = asyncio.new_event_loop()
    thread = threading.Thread(
        target=loop.run_forever, daemon=True, name="ldr-emit-contract-loop"
    )
    thread.start()

    async def _make_lock():
        sio_mod._lock = asyncio.Lock()

    # The real lock is built once at lifespan startup and belongs to the loop
    # that created it; a lock left over from another test's dead loop raises
    # on the next acquire.
    asyncio.run_coroutine_threadsafe(_make_lock(), loop).result(timeout=5)
    return loop, thread


@pytest.fixture
def worker_loop(monkeypatch):
    """A real running loop installed as the module's captured main loop --
    what ``set_main_loop`` does under uvicorn, and the only configuration in
    which the sync wrappers do anything.

    The test body itself plays the research worker: it runs on a thread with
    no running loop of its own, exactly like ``run_research_process``.
    """
    saved_lock = sio_mod._lock
    loop, thread = _start_loop_thread()
    monkeypatch.setattr(sio_mod, "_main_loop", loop)
    try:
        yield loop
    finally:
        sio_mod._lock = saved_lock
        loop.call_soon_threadsafe(loop.stop)
        thread.join(timeout=5)
        loop.close()


@pytest.fixture
def dead_loop(monkeypatch):
    """A loop that has been stopped but not closed -- the shutdown state a
    worker thread can still hold a reference to."""
    saved_lock = sio_mod._lock
    loop, thread = _start_loop_thread()
    loop.call_soon_threadsafe(loop.stop)
    thread.join(timeout=5)
    assert not loop.is_running(), "fixture precondition: loop must be stopped"
    assert not loop.is_closed(), "fixture precondition: loop must be open"
    monkeypatch.setattr(sio_mod, "_main_loop", loop)
    try:
        yield loop
    finally:
        sio_mod._lock = saved_lock
        loop.close()


@pytest.fixture
def subscribed(monkeypatch):
    """One owner with one subscribed socket, plus a recording ``sio.emit``.

    ``_sid_sessions`` is left empty on purpose: the fanout's session-touch
    step is keyed off it, and it is not what this file is about.
    """
    monkeypatch.setattr(sio_mod, "_subscriptions", {(OWNER, RID): {SID}})
    monkeypatch.setattr(sio_mod, "_sid_users", {SID: OWNER})
    monkeypatch.setattr(sio_mod, "_sid_sessions", {})

    delivered: list[tuple] = []

    async def _record(event, data=None, room=None):
        delivered.append((room, event, data))

    monkeypatch.setattr(sio_mod.sio, "emit", _record)
    return delivered


@contextlib.contextmanager
def _captured_schedules():
    """Grab the Futures the module discards, so a test can wait on them.

    Production drops them, so this is the only way to know a scheduled
    coroutine has finished without polling or sleeping.
    """
    captured: list[concurrent.futures.Future] = []
    real = asyncio.run_coroutine_threadsafe

    def _capture(coro, loop):
        future = real(coro, loop)
        captured.append(future)
        return future

    with patch.object(asyncio, "run_coroutine_threadsafe", _capture):
        yield captured


def _settle(captured) -> list:
    """Wait for every captured coroutine and return their exceptions.

    Must be called while the ``sio``/``logger`` patches are still active --
    the coroutines resolve those module globals when they run.
    """
    concurrent.futures.wait(captured, timeout=10)
    return [f.exception(timeout=5) for f in captured]


# ---------------------------------------------------------------------------
# 1. Who can receive a roomless emit
# ---------------------------------------------------------------------------


class _PacketRecorder:
    """Stands in for the engine.io write, one call per recipient socket."""

    def __init__(self):
        self.sent: list[str] = []

    async def __call__(self, eio_sid, pkt):
        self.sent.append(eio_sid)


@pytest.fixture
def two_connected_users(monkeypatch):
    """Two sockets belonging to two DIFFERENT users, registered with the real
    ``AsyncServer``'s real manager.

    Nothing here is a stand-in for the routing decision: ``manager.connect``
    is the same call the live connect handler's return path triggers, and the
    room bookkeeping it produces is what ``sio.emit`` reads.
    """
    manager = sio_mod.sio.manager
    monkeypatch.setattr(manager, "rooms", {})

    async def _connect_both():
        # AsyncManager.connect is a coroutine wrapper over the sync
        # bookkeeping; the room dicts it fills are plain dicts, so which loop
        # ran it does not matter to the emit under test.
        return (
            await manager.connect("eio-alice", "/"),
            await manager.connect("eio-bob", "/"),
        )

    alice_sid, bob_sid = asyncio.run(_connect_both())
    assert alice_sid and bob_sid and alice_sid != bob_sid

    recorder = _PacketRecorder()
    monkeypatch.setattr(sio_mod.sio, "_send_eio_packet", recorder)
    return alice_sid, bob_sid, recorder


class TestWhoCanReceiveARoomlessEmit:
    """``room=None`` is the whole namespace, not a default room."""

    def test_a_roomless_emit_reaches_every_connected_user(
        self, two_connected_users
    ):
        """Alice's data, emitted without a room, lands on Bob's socket."""
        _alice, _bob, recorder = two_connected_users

        asyncio.run(
            sio_mod._async_emit(
                "parallel_search_started",
                {"query": "alice's private research question"},
                None,
            )
        )

        assert set(recorder.sent) == {"eio-alice", "eio-bob"}, (
            "a roomless emit was expected to fan out to every connected "
            f"socket; recipients were {recorder.sent}"
        )

    def test_positive_control_a_room_reaches_only_that_socket(
        self, two_connected_users
    ):
        """The same call path, given a room, is correctly scoped -- so the
        broadcast above is the ``room=None`` argument and nothing else."""
        alice_sid, _bob, recorder = two_connected_users

        asyncio.run(
            sio_mod._async_emit(
                "parallel_search_started",
                {"query": "alice's private research question"},
                alice_sid,
            )
        )

        assert recorder.sent == ["eio-alice"]

    def test_the_sync_wrapper_defaults_to_the_broadcast(
        self, two_connected_users, worker_loop
    ):
        """``emit_socket_event(event, data)`` -- the whole public signature a
        caller sees -- takes the broadcast branch, from a worker thread."""
        _alice, _bob, recorder = two_connected_users

        with _captured_schedules() as captured:
            scheduled = sio_mod.emit_socket_event(
                "some_event", {"detail": "attacker-influenced text"}
            )

        assert scheduled is True
        assert _settle(captured) == [None]
        assert set(recorder.sent) == {"eio-alice", "eio-bob"}

    def test_the_broadcast_has_one_caller_and_that_caller_has_none(self):
        """Reachability, pinned by AST over the whole production package.

        SECURITY GUARD. Today nothing can reach the broadcast: the single
        caller of ``emit_socket_event`` is the ``emit_to_room`` adapter, and
        ``emit_to_room`` is never called. If either fact changes, whatever
        data that new call site passes goes to every logged-in user's
        browser -- re-derive the payload before relaxing this test.
        """
        broadcast_callers = _call_sites("emit_socket_event")
        assert len(broadcast_callers) == 1, (
            "expected exactly one call to emit_socket_event in the package, "
            f"found: {broadcast_callers}"
        )
        rel, qualname, _line = broadcast_callers[0]
        assert rel == "benchmarks/web_api/benchmark_service.py"
        assert qualname == "SocketIOService.emit_to_room"

        adapter_callers = _call_sites("emit_to_room")
        assert adapter_callers == (), (
            "SocketIOService.emit_to_room now has a caller. It forwards to "
            "emit_socket_event, whose room defaults to None, which delivers "
            "to EVERY connected client across all users -- see "
            "test_a_roomless_emit_reaches_every_connected_user. Confirm the "
            f"payload is safe for that audience: {adapter_callers}"
        )


# ---------------------------------------------------------------------------
# 2. The sync seam is total
# ---------------------------------------------------------------------------


class TestTheSyncSeamIsTotal:
    """A research worker must be able to call these and keep going."""

    def test_positive_control_a_healthy_emit_is_delivered(
        self, worker_loop, subscribed
    ):
        with _captured_schedules() as captured:
            ok = sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 42}, owner=OWNER
            )
        assert ok is True
        assert _settle(captured) == [None]
        assert subscribed == [
            (SID, f"research_progress_{RID}", {"progress": 42})
        ]

    def test_no_captured_loop_returns_false_without_raising(
        self, monkeypatch, subscribed
    ):
        """Pre-startup, or in any process that never ran the lifespan."""
        monkeypatch.setattr(sio_mod, "_main_loop", None)
        assert (
            sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 1}, owner=OWNER
            )
            is False
        )
        assert subscribed == []

    def test_a_closed_loop_returns_false_without_raising(
        self, monkeypatch, subscribed
    ):
        """Post-shutdown. ``_get_main_loop`` rejects a closed loop and the
        worker-thread fallback finds no running loop either."""
        loop, thread = _start_loop_thread()
        saved_lock = sio_mod._lock
        loop.call_soon_threadsafe(loop.stop)
        thread.join(timeout=5)
        loop.close()
        sio_mod._lock = saved_lock
        monkeypatch.setattr(sio_mod, "_main_loop", loop)

        assert (
            sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 1}, owner=OWNER
            )
            is False
        )
        assert subscribed == []

    def test_an_uninitialised_lock_reports_success_and_delivers_nothing(
        self, worker_loop, subscribed
    ):
        """DEFECT (silent): ``_lock`` is ``None`` until ``init_lock()`` runs,
        but the wrapper only checks the loop.

        ``set_main_loop`` is called before ``init_lock`` in the lifespan, so
        between those two statements -- and in any embedding that captures a
        loop without initialising the lock -- ``emit_to_subscribers`` returns
        ``True`` while the coroutine dies on ``async with None``. The Future
        carrying that TypeError is discarded, so nothing is logged and the
        caller records a successful emit.
        """
        sio_mod._lock = None

        with _captured_schedules() as captured:
            reported = sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 42}, owner=OWNER
            )
            errors = _settle(captured)

        assert reported is True, "the wrapper reported success"
        assert subscribed == [], "yet nothing was delivered"
        assert isinstance(errors[0], TypeError), (
            "the coroutine failed on the uninitialised lock, and its Future "
            f"is discarded in production; got {errors[0]!r}"
        )

    def test_an_unencodable_payload_stays_on_the_loop_thread(
        self, worker_loop, two_connected_users, monkeypatch
    ):
        """A payload the real transport cannot encode fails per-subscriber.

        Driven through the real ``sio.emit`` and the real packet encoder --
        the TypeError is genuinely raised by python-socketio, not injected.
        """
        alice_sid, _bob, recorder = two_connected_users
        monkeypatch.setattr(
            sio_mod, "_subscriptions", {(OWNER, RID): {alice_sid}}
        )
        monkeypatch.setattr(sio_mod, "_sid_users", {alice_sid: OWNER})
        monkeypatch.setattr(sio_mod, "_sid_sessions", {})

        with _captured_schedules() as captured:
            reported = sio_mod.emit_to_subscribers(
                "research_progress", RID, {"handle": object()}, owner=OWNER
            )
            errors = _settle(captured)

        assert reported is True
        assert errors == [None], (
            "the encoder failure must be swallowed inside the fanout, not "
            f"left on the discarded Future: {errors}"
        )
        assert recorder.sent == [], "nothing could be encoded, so nothing sent"

        # Positive control: the channel is not poisoned -- the next frame for
        # the same research still reaches the same socket.
        with _captured_schedules() as captured:
            sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 43}, owner=OWNER
            )
            assert _settle(captured) == [None]
        assert recorder.sent == ["eio-alice"]

    def test_a_production_call_site_relies_on_that_totality(self):
        """At least one emit call site has no ``try`` of its own.

        Not decoration: ``_save_chat_message_and_context`` emits the final
        ``response_chunk`` unguarded, so a raise from the wrapper would abort
        the chat-persist path rather than costing one frame. The nearest
        handler is in the caller, several frames out.
        """
        path = _PKG_ROOT / "web" / "services" / "research_service.py"
        tree = ast.parse(path.read_text(encoding="utf-8"))
        spans = _guarded_line_spans(tree)

        visitor = _CallSites({"emit_to_subscribers"})
        visitor.visit(tree)
        assert visitor.found, "no emit call sites found -- scan is broken"

        unguarded = [
            qual
            for qual, line in visitor.found
            if not any(start <= line <= end for start, end in spans)
        ]
        assert unguarded, (
            "every emit call site is now individually wrapped in try/except; "
            "if that is deliberate, this test can go -- but check the "
            "wrappers still cannot raise before removing the ones above"
        )
        assert "_save_chat_message_and_context" in unguarded


# ---------------------------------------------------------------------------
# 3. The loop is gone at shutdown
# ---------------------------------------------------------------------------


class TestTheLoopIsGoneAtShutdown:
    """Two shapes of "the loop went away", only one of which is detected."""

    def test_a_stopped_loop_is_refused_before_scheduling(
        self, dead_loop, subscribed
    ):
        """The detected shape: ``is_running()`` is already False at the check."""
        with _captured_schedules() as captured:
            reported = sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 42}, owner=OWNER
            )

        assert reported is False
        assert captured == [], "nothing should have been scheduled at all"
        assert subscribed == []

    def test_the_check_then_schedule_race_reports_success_and_strands_it(
        self, dead_loop, subscribed
    ):
        """The undetected shape: the loop stops between the check and the
        schedule.

        ``is_running()`` is read once, then ``run_coroutine_threadsafe`` is
        called; a loop that stops in that window is still OPEN, so the
        schedule succeeds, the wrapper returns ``True``, and the coroutine
        sits in a ready queue that will never be drained. Patching
        ``is_running`` for the duration of the wrapper call reproduces
        exactly that interleaving deterministically.
        """
        with _captured_schedules() as captured:
            with patch.object(dead_loop, "is_running", return_value=True):
                reported = sio_mod.emit_to_subscribers(
                    "research_progress", RID, {"progress": 42}, owner=OWNER
                )

            assert reported is True, "the wrapper reported success"
            assert len(captured) == 1, "and did schedule the coroutine"
            assert not captured[0].done(), (
                "but the loop is not running, so it never started"
            )
            assert subscribed == [], "nothing was delivered"

            # It was stranded, not rejected: give the loop a chance to run
            # again and the same frame is delivered -- late, long after the
            # worker recorded a successful emit and moved on.
            for _ in range(20):
                if captured[0].done():
                    break
                dead_loop.run_until_complete(asyncio.sleep(0))

        assert captured[0].done()
        assert subscribed == [
            (SID, f"research_progress_{RID}", {"progress": 42})
        ]


# ---------------------------------------------------------------------------
# 4. Delivery order is scheduling order
# ---------------------------------------------------------------------------


class TestDeliveryOrderIsSchedulingOrderOnly:
    """The completion path leans on FIFO; nothing restores logical order."""

    def test_positive_control_the_completion_sequence_arrives_in_order(
        self, worker_loop, subscribed
    ):
        """One thread, the real shape of ``cleanup_research_resources``:
        progress, then the terminal frame, then the subscription teardown."""
        with _captured_schedules() as captured:
            sio_mod.emit_to_subscribers(
                "research_progress", RID, {"progress": 90}, owner=OWNER
            )
            sio_mod.emit_to_subscribers(
                "research_progress",
                RID,
                {"status": "completed", "progress": 100},
                owner=OWNER,
            )
            sio_mod.remove_subscriptions_for_research(RID, OWNER)
            assert _settle(captured) == [None, None, None]

        assert [payload for _room, _event, payload in subscribed] == [
            {"progress": 90},
            {"status": "completed", "progress": 100},
        ]
        assert (OWNER, RID) not in sio_mod._subscriptions, (
            "the teardown was scheduled last and must land last"
        )

    def test_a_progress_frame_scheduled_later_is_delivered_after_the_terminal(
        self, worker_loop, subscribed
    ):
        """A terminal event CAN precede a progress event that logically
        precedes it.

        Two threads emit for one research: the worker running
        ``cleanup_research_resources``, and any thread whose log line reaches
        ``frontend_progress_sink`` -- including the parallel-search workers,
        which inherit ``research_id`` through ``thread_context``'s ContextVar.
        The interleaving here is chosen rather than raced, and the point is
        what the layer does about it: nothing. There is no sequence number,
        no per-research ordering key, and no suppression after a terminal
        status, so the client is handed "completed" and then a 30% progress
        line.
        """
        terminal_done = threading.Event()
        errors: list[BaseException] = []

        def _worker_thread():
            try:
                sio_mod.emit_to_subscribers(
                    "research_progress",
                    RID,
                    {"status": "completed", "progress": 100},
                    owner=OWNER,
                )
            except BaseException as exc:  # noqa: BLE001 - reported below
                errors.append(exc)
            finally:
                terminal_done.set()

        def _search_thread():
            try:
                assert terminal_done.wait(timeout=5), "handshake never fired"
                sio_mod.emit_to_subscribers(
                    "research_progress",
                    RID,
                    {"log_entry": {"message": "still fetching page 3"}},
                    owner=OWNER,
                )
            except BaseException as exc:  # noqa: BLE001 - reported below
                errors.append(exc)

        with _captured_schedules() as captured:
            threads = [
                threading.Thread(target=_worker_thread),
                threading.Thread(target=_search_thread),
            ]
            for t in threads:
                t.start()
            for t in threads:
                t.join(timeout=5)
            assert not errors, f"an emitting thread raised: {errors}"
            assert len(captured) == 2
            assert _settle(captured) == [None, None]

        payloads = [payload for _room, _event, payload in subscribed]
        assert payloads[0]["status"] == "completed"
        assert "log_entry" in payloads[1], (
            "the later-scheduled progress frame is delivered after the "
            f"terminal one, unchanged and unsuppressed: {payloads}"
        )


# ---------------------------------------------------------------------------
# 5. The payload is not copied at the seam
# ---------------------------------------------------------------------------


class TestThePayloadCrossesTheSeamByReference:
    """What is sent is read on the loop thread, after the caller returned."""

    def test_the_wire_payload_is_the_callers_own_object(
        self, worker_loop, subscribed
    ):
        payload = {"progress": 10}
        with _captured_schedules() as captured:
            sio_mod.emit_to_subscribers(
                "research_progress", RID, payload, owner=OWNER
            )
            assert _settle(captured) == [None]

        assert subscribed[0][2] is payload, (
            "the layer neither copies the payload nor wraps it in an envelope"
        )

    def test_a_mutation_after_the_call_changes_what_is_sent(
        self, worker_loop, monkeypatch
    ):
        """Consequence of the above, made deterministic.

        The emit is held on the loop until the caller has already returned
        and mutated its dict; the value that reaches the transport is the
        mutated one. No current call site mutates a payload after emitting --
        every one builds a fresh dict -- so this pins the property, not a
        live bug. It matters because the natural fix for a hot progress path
        (reuse one dict, update the fields) would silently rewrite frames
        that are already "sent".
        """
        monkeypatch.setattr(sio_mod, "_subscriptions", {(OWNER, RID): {SID}})
        monkeypatch.setattr(sio_mod, "_sid_users", {SID: OWNER})
        monkeypatch.setattr(sio_mod, "_sid_sessions", {})

        gate: dict = {}

        async def _make_gate():
            gate["event"] = asyncio.Event()

        asyncio.run_coroutine_threadsafe(_make_gate(), worker_loop).result(
            timeout=5
        )

        sent: list = []

        async def _record(event, data=None, room=None):
            await gate["event"].wait()
            # Snapshot by value: this is what actually goes on the wire.
            sent.append(copy.deepcopy(data))

        monkeypatch.setattr(sio_mod.sio, "emit", _record)

        payload = {"progress": 10}
        with _captured_schedules() as captured:
            assert (
                sio_mod.emit_to_subscribers(
                    "research_progress", RID, payload, owner=OWNER
                )
                is True
            )
            # The caller has returned; from its point of view the frame
            # carrying progress=10 is already gone.
            payload["progress"] = 100
            worker_loop.call_soon_threadsafe(gate["event"].set)
            assert _settle(captured) == [None]

        assert sent == [{"progress": 100}], (
            "the value read on the loop thread is the post-call one"
        )