inline-core 1.1.1__py3-none-any.whl

inline_core/server/app.py

@@ -0,0 +1,327 @@
+"""The FastAPI app: the /v1 routes from docs/contract.md over the run manager and registry."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import re
+import tempfile
+from contextlib import asynccontextmanager
+from os.path import basename
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+
+from fastapi import FastAPI, Request, Response, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from ..config import models_dir
+from ..device.memory import MemoryPolicy
+from ..device.policy import DevicePolicy
+from ..errors import GraphValidationError, UnknownNodeType
+from ..graph.cache import InMemoryCache, NodeCache
+from ..graph.registry import Registry, build_default_registry
+from ..graph.schema import SCHEMA_VERSION, parse_graph
+from ..models.catalog import ModelCatalog
+from .assets import AssetStore
+from .manager import RunConflict, RunManager
+from .rpc import EventBroadcaster, RpcRouter
+from .run_store import RunStore
+from .serialize import descriptor_json, event_json, run_json, take_json
+
+# GET /v1/runs/<id> (the client's run-status poll) — but not /events or nested paths.
+_RUN_POLL_PATH = re.compile(r"^/v1/runs/[^/]+$")
+
+
+class _SuppressRunPolling(logging.Filter):
+    """Drop the flood of run-status poll requests from the uvicorn access log.
+
+    Studio polls ``GET /v1/runs/<id>`` sub-second while a run is in flight, which buries the
+    generation progress bar under identical 200 lines. We hide only those successful polls;
+    submits, cancels, errors, and every other request still log normally.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        args = record.args
+        if not isinstance(args, tuple) or len(args) < 5:
+            return True
+        method, path, status = args[1], args[2], args[4]
+        if method == "GET" and status == 200 and _RUN_POLL_PATH.match(str(path)):
+            return False
+        return True
+
+
+def _quiet_run_polling() -> None:
+    """Install the poll-suppressing access-log filter once (idempotent across create_app calls)."""
+    access = logging.getLogger("uvicorn.access")
+    if not any(isinstance(f, _SuppressRunPolling) for f in access.filters):
+        access.addFilter(_SuppressRunPolling())
+
+
+def _within(root: Path, path: Path) -> bool:
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _error(code: str, message: str, status: int, node_id: str | None = None) -> JSONResponse:
+    error: dict[str, Any] = {"code": code, "message": message}
+    if node_id is not None:
+        error["nodeId"] = node_id
+    return JSONResponse({"error": error}, status_code=status)
+
+
+def _version(registry: Registry, catalog: ModelCatalog) -> str:
+    """Registry version = node types + the scanned model files, so dropping a file bumps it."""
+    payload = json.dumps(
+        {"types": sorted(d.type for d in registry.descriptors()), "models": catalog.fingerprint()}
+    )
+    return f"r_{hashlib.sha256(payload.encode()).hexdigest()[:8]}"
+
+
+def create_app(
+    registry: Registry | None = None,
+    cache: NodeCache | None = None,
+    policy: DevicePolicy | None = None,
+    asset_dir: str | None = None,
+    models_root: str | None = None,
+    run_store: RunStore | None = None,
+    takes_dir: str | None = None,
+    frontend_root: str | None = None,
+    rpc: RpcRouter | None = None,
+    events: EventBroadcaster | None = None,
+    studio_store: Any = None,
+) -> FastAPI:
+    _quiet_run_polling()
+    registry = registry or build_default_registry()
+    cache = cache or InMemoryCache()
+    policy = policy or MemoryPolicy()
+    assets = AssetStore(Path(asset_dir or "./.inline-assets"))
+    catalog = ModelCatalog(Path(models_root) if models_root else models_dir())
+    takes_root = Path(takes_dir or "./.inline-takes")
+    manager = RunManager(registry, cache, policy, store=run_store)
+    rpc = rpc or RpcRouter()
+    events = events or EventBroadcaster()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):  # noqa: ANN202
+        manager.bind_loop(asyncio.get_running_loop())
+        catalog.ensure_dirs()
+        catalog.scan()
+        yield
+        manager.shutdown()
+
+    app = FastAPI(title="Inline Core", version="0.0.0", lifespan=lifespan)
+
+    @app.get("/v1/health")
+    async def health() -> dict[str, Any]:
+        placement = policy.placement("denoiser")
+        return {
+            "ok": True,
+            "apiVersion": "v1",
+            "schemaVersions": {"min": SCHEMA_VERSION, "max": SCHEMA_VERSION},
+            "registryVersion": _version(registry, catalog),
+            "device": {
+                "kind": placement.device.kind.value,
+                "profile": policy.profile.value,
+                "vramBudgetMb": None,
+            },
+        }
+
+    @app.get("/v1/models")
+    async def list_models(request: Request) -> Response:
+        version = _version(registry, catalog)
+        etag = f'"{version}"'
+        if request.headers.get("if-none-match") == etag:
+            return Response(status_code=304)
+        body = {
+            "registryVersion": version,
+            "models": [descriptor_json(d, catalog) for d in registry.descriptors()],
+        }
+        return JSONResponse(body, headers={"ETag": etag})
+
+    @app.get("/v1/models/{model_type:path}")
+    async def get_model(model_type: str) -> Response:
+        try:
+            return JSONResponse(descriptor_json(registry.get(model_type), catalog))
+        except UnknownNodeType as error:
+            return _error("not_found", str(error), 404)
+
+    @app.post("/v1/runs")
+    async def submit_run(request: Request) -> Response:
+        body = await request.json()
+        target = body.get("target")
+        if not isinstance(target, str):
+            return _error("invalid_request", "'target' is required.", 422)
+        try:
+            graph = parse_graph(body.get("graph"))
+            record, created = manager.submit(graph, target, body.get("clientRunId"))
+        except GraphValidationError as error:
+            return _error("invalid_graph", str(error), 422, node_id=error.node_id)
+        except RunConflict as error:
+            return _error("conflict", str(error), 409)
+        return JSONResponse(
+            {"runId": record.state.run_id, "status": record.state.status.value},
+            status_code=201 if created else 200,
+        )
+
+    @app.get("/v1/runs/{run_id}")
+    async def get_run(run_id: str) -> Response:
+        record = manager.get(run_id)
+        if record is None:
+            return _error("not_found", f"No run {run_id!r}.", 404)
+        return JSONResponse(run_json(record.state))
+
+    @app.delete("/v1/runs/{run_id}")
+    async def cancel_run(run_id: str) -> Response:
+        if not manager.cancel(run_id):
+            return _error("not_found", f"No run {run_id!r}.", 404)
+        return JSONResponse({"runId": run_id, "status": "cancelled"})
+
+    @app.post("/v1/assets")
+    async def upload_asset(request: Request) -> Response:
+        data = await request.body()
+        stored = assets.put(data, request.headers.get("content-type"))
+        return JSONResponse({"id": stored.id, "kind": stored.kind.value, "bytes": stored.size})
+
+    @app.get("/v1/takes/{take_id}")
+    async def get_take(take_id: str) -> Response:
+        take = manager.find_take(take_id)
+        if take is None:
+            return _error("not_found", f"No take {take_id!r}.", 404)
+        return JSONResponse(take_json(take))
+
+    @app.get("/v1/takes/{take_id}/bytes")
+    async def get_take_bytes(take_id: str) -> Response:
+        take = manager.find_take(take_id)
+        if take is None:
+            return _error("not_found", f"No take {take_id!r}.", 404)
+        path = Path(take.uri)
+        if not _within(takes_root, path) or not path.is_file():
+            return _error("not_found", "Take bytes are not available.", 404)
+        return FileResponse(path)
+
+    @app.websocket("/v1/runs/{run_id}/events")
+    async def run_events(websocket: WebSocket, run_id: str) -> None:
+        record = manager.get(run_id)
+        if record is None:
+            await websocket.close(code=4404)
+            return
+        await websocket.accept()
+        queue: asyncio.Queue[Any] = asyncio.Queue()
+        record.subscribers.add(queue)
+        try:
+            await websocket.send_json(
+                {"type": "snapshot", "runId": run_id, "state": run_json(record.state)}
+            )
+            if record.done:
+                return
+            while True:
+                event = await queue.get()
+                if event is None:
+                    break
+                await websocket.send_json(event_json(event))
+        finally:
+            record.subscribers.discard(queue)
+
+    # The Studio app-backend bridge (strangler-fig): the SPA posts InlineStudioApi calls here.
+    # Native handlers answer ported channels; the rest proxy to the legacy Node backend (rpc.py).
+    @app.post("/rpc")
+    async def rpc_dispatch(request: Request) -> Response:
+        body = await request.json()
+        channel = body.get("channel")
+        args = body.get("args") or []
+        if not isinstance(channel, str):
+            return JSONResponse({"ok": False, "error": "Missing 'channel'."})
+        if not isinstance(args, list):
+            return JSONResponse({"ok": False, "error": "'args' must be a list."})
+        return JSONResponse(await rpc.dispatch(channel, args))
+
+    @app.websocket("/events")
+    async def studio_events(websocket: WebSocket) -> None:
+        await websocket.accept()
+        queue = events.add()
+        try:
+            while True:
+                await websocket.send_json(await queue.get())
+        except WebSocketDisconnect:
+            pass
+        finally:
+            events.remove(queue)
+
+    # The native Studio app-backend: register the InlineStudioApi channels on the RpcRouter +
+    # project media/uploads (the B1 flip — Core becomes the sole backend, no Node proxy).
+    if studio_store is not None:
+        from ..studio.fal import FalGeneration
+        from ..studio.generation import CoreGeneration
+        from ..studio.handlers import register_studio_handlers
+        from ..studio.models import ModelDownloads
+        from ..studio.timeline.render import Timeline
+
+        def core_models() -> dict[str, Any]:
+            return {
+                "registryVersion": _version(registry, catalog),
+                "models": [descriptor_json(d, catalog) for d in registry.descriptors()],
+            }
+
+        def core_status() -> dict[str, Any]:
+            return {"running": True, "url": ""}
+
+        register_studio_handlers(
+            rpc,
+            studio_store,
+            core_models=core_models,
+            core_status=core_status,
+            generation=CoreGeneration(studio_store, manager, events),
+            fal_generation=FalGeneration(studio_store, events),
+            timeline=Timeline(studio_store, events),
+            # Explicit model downloads write into models/; rescan so new files bump the registry.
+            model_downloads=ModelDownloads(events, on_change=catalog.rescan),
+        )
+
+        @app.get("/media/{media_path:path}")
+        async def media(media_path: str, request: Request) -> Response:
+            try:
+                root = studio_store.folder().resolve()
+            except RuntimeError:
+                return Response("No project open", status_code=404)
+            rel = unquote(media_path).lstrip("/")
+            target = (root / rel).resolve()
+            if target != root and root not in target.parents:
+                return Response("Forbidden", status_code=403)
+            if not target.is_file():
+                return Response("Not found", status_code=404)
+            return FileResponse(target)  # Range-aware; Content-Type guessed from the extension
+
+        @app.post("/upload")
+        async def upload(request: Request) -> Response:
+            from ..studio import assets as ax
+
+            name = basename(request.query_params.get("name") or "upload") or "upload"
+            folder_id = request.query_params.get("folderId") or None
+            body = await request.body()
+            try:
+                with tempfile.TemporaryDirectory() as tmp:
+                    path = Path(tmp) / name
+                    path.write_bytes(body)
+                    asset = ax.import_file(
+                        studio_store.conn(), studio_store.folder(), str(path), folder_id
+                    )
+                if asset is not None:
+                    events.broadcast("events:libraryChanged", None)
+                return JSONResponse({"ok": True, "value": asset})
+            except Exception as error:  # noqa: BLE001
+                return JSONResponse({"ok": False, "error": str(error)})
+
+    # Serve the Inline Studio SPA on this same port when a frontend is available. Mounted LAST so
+    # every /v1 and /rpc route above still wins; StaticFiles(html=True) serves index.html at "/" and
+    # the hashed assets, giving the one-port experience (mirrors ComfyUI's frontend package).
+    if frontend_root and (Path(frontend_root) / "index.html").is_file():
+        app.mount("/", StaticFiles(directory=frontend_root, html=True), name="frontend")
+
+    return app

inline_core/server/assets.py

@@ -0,0 +1,47 @@
+"""Content-addressed input store: id = sha256 of the bytes, so re-uploading a file dedupes."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..media import MediaKind
+
+_KIND_BY_PREFIX = {
+    "image/": MediaKind.IMAGE,
+    "video/": MediaKind.VIDEO,
+    "audio/": MediaKind.AUDIO,
+}
+
+
+@dataclass(frozen=True)
+class StoredAsset:
+    id: str
+    kind: MediaKind
+    size: int
+
+
+class AssetStore:
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def put(self, data: bytes, content_type: str | None) -> StoredAsset:
+        self._root.mkdir(parents=True, exist_ok=True)
+        asset_id = f"sha256-{hashlib.sha256(data).hexdigest()}"
+        path = self._root / asset_id
+        if not path.exists():
+            path.write_bytes(data)
+        return StoredAsset(id=asset_id, kind=_kind_for(content_type), size=len(data))
+
+    def path(self, asset_id: str) -> Path | None:
+        candidate = self._root / asset_id
+        return candidate if candidate.exists() else None
+
+
+def _kind_for(content_type: str | None) -> MediaKind:
+    if content_type:
+        for prefix, kind in _KIND_BY_PREFIX.items():
+            if content_type.startswith(prefix):
+                return kind
+    return MediaKind.IMAGE

inline_core/server/bootstrap.py

@@ -0,0 +1,21 @@
+"""Best-effort model registration. A model whose deps are absent is skipped; the engine still serves
+source nodes and the rest of the API, so a torch-less install boots cleanly.
+"""
+
+from __future__ import annotations
+
+from ..device.policy import DevicePolicy
+from ..graph.registry import Registry
+from ..runtime.store import TakeStore
+
+
+def register_models(registry: Registry, store: TakeStore, policy: DevicePolicy) -> list[str]:
+    registered: list[str] = []
+    try:
+        from ..models.zimage.runner import register_zimage
+
+        register_zimage(registry, store, policy)
+        registered.append("alibaba/z-image-turbo")
+    except ImportError:
+        pass
+    return registered

inline_core/server/frontend.py

@@ -0,0 +1,37 @@
+"""Locate the Inline Studio frontend Core serves on its own port (mirrors ComfyUI's frontend pkg).
+
+Resolution order, most specific first:
+  1. ``INLINE_FRONTEND_ROOT`` — a local SPA build dir (set directly or via ``main.py
+     --front-end-root``); the dev loop — rebuild the UI locally without republishing the package.
+  2. the installed ``inline_studio_frontend`` package's ``static/`` dir — the default for end users
+     (``pip install`` pulls the built frontend; no Node needed).
+  3. ``None`` — Core runs API-only (no UI mounted).
+
+A dir only counts when it actually holds an ``index.html``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _has_index(path: Path) -> bool:
+    return (path / "index.html").is_file()
+
+
+def resolve_frontend_root() -> str | None:
+    env = os.environ.get("INLINE_FRONTEND_ROOT", "").strip()
+    if env:
+        root = Path(env)
+        return str(root) if _has_index(root) else None
+
+    try:
+        import inline_studio_frontend  # type: ignore[import-not-found]
+    except ModuleNotFoundError:
+        return None
+    pkg_file = getattr(inline_studio_frontend, "__file__", None)
+    if not pkg_file:
+        return None
+    static = Path(pkg_file).parent / "static"
+    return str(static) if _has_index(static) else None

inline_core/server/manager.py

@@ -0,0 +1,195 @@
+"""The run manager: validate, queue, execute on a worker thread, fan out events to subscribers.
+
+The durable RunState is authoritative (GET /v1/runs). The websocket stream is a fan-out on top; the
+state is updated on the worker thread (via the executor's StateTrackingEmitter) before each publish.
+A RunStore persists runs so they survive a restart; progress events are coalesced to the stream.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from uuid import uuid4
+
+from ..device.memory import MemoryPolicy
+from ..device.policy import DevicePolicy
+from ..errors import InlineCoreError
+from ..graph.cache import NodeCache
+from ..graph.executor import Executor
+from ..graph.registry import Registry
+from ..graph.schema import Graph
+from ..graph.topo import topo_sort, upstream_closure
+from ..graph.validate import validate
+from ..runtime.context import CancelToken, ExecutionContext
+from ..runtime.progress import ProgressEmitter, ProgressEvent, RunEvent
+from ..runtime.run import NodeRuntimeState, RunState
+from ..takes import Take
+from .run_store import RunStore
+
+# ~10 progress events per second per run to the stream (contract section 6). The snapshot stays
+# authoritative, so dropping intermediate ticks only affects stream chattiness.
+_MIN_PROGRESS_INTERVAL = 0.1
+
+
+class RunConflict(InlineCoreError):
+    """A clientRunId was reused with a different graph."""
+
+
+class RunRecord:
+    def __init__(self, state: RunState, cancel: CancelToken) -> None:
+        self.state = state
+        self.cancel = cancel
+        self.subscribers: set[asyncio.Queue[RunEvent | None]] = set()
+        self.done = False
+        self.last_progress = 0.0
+
+
+class _BroadcastEmitter(ProgressEmitter):
+    def __init__(self, manager: RunManager, record: RunRecord) -> None:
+        self._manager = manager
+        self._record = record
+
+    def emit(self, event: RunEvent) -> None:
+        self._manager.publish(self._record, event)
+
+
+class RunManager:
+    def __init__(
+        self,
+        registry: Registry,
+        cache: NodeCache,
+        policy: DevicePolicy | None = None,
+        workers: int = 1,
+        store: RunStore | None = None,
+    ) -> None:
+        self._registry = registry
+        self._cache = cache
+        self._policy = policy or MemoryPolicy()
+        self._pool = ThreadPoolExecutor(max_workers=workers, thread_name_prefix="run")
+        self._runs: dict[str, RunRecord] = {}
+        self._by_client: dict[str, str] = {}
+        self._graph_hash: dict[str, str] = {}
+        self._lock = threading.Lock()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._store = store
+        if store is not None:
+            store.interrupt_stale()
+
+    def bind_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+
+    def shutdown(self) -> None:
+        for record in list(self._runs.values()):
+            record.cancel.cancel()
+        self._pool.shutdown(wait=False)
+
+    def submit(
+        self, graph: Graph, target: str, client_run_id: str | None = None
+    ) -> tuple[RunRecord, bool]:
+        validate(graph, target, self._registry)
+        graph_hash = _graph_hash(graph, target)
+        if client_run_id is not None and client_run_id in self._by_client:
+            existing = self._runs[self._by_client[client_run_id]]
+            if self._graph_hash.get(existing.state.run_id) == graph_hash:
+                return existing, False
+            raise RunConflict(f"clientRunId {client_run_id!r} was reused with a different graph.")
+        run_id = f"run_{uuid4().hex[:12]}"
+        state = RunState(run_id=run_id, target=target)
+        for node_id in topo_sort(
+            list(upstream_closure(target, graph.input_sources)), graph.input_sources
+        ):
+            state.nodes[node_id] = NodeRuntimeState()
+        record = RunRecord(state, CancelToken())
+        with self._lock:
+            self._runs[run_id] = record
+            if client_run_id is not None:
+                self._by_client[client_run_id] = run_id
+                self._graph_hash[run_id] = graph_hash
+        if self._store is not None:
+            self._store.create(state, client_run_id)
+        self._pool.submit(self._execute, graph, target, record)
+        return record, True
+
+    def get(self, run_id: str) -> RunRecord | None:
+        record = self._runs.get(run_id)
+        if record is not None:
+            return record
+        if self._store is not None:
+            state = self._store.load(run_id)
+            if state is not None:
+                return _historical(state)
+        return None
+
+    def cancel(self, run_id: str) -> bool:
+        record = self._runs.get(run_id)
+        if record is None:
+            return False
+        record.cancel.cancel()
+        return True
+
+    def find_take(self, take_id: str) -> Take | None:
+        for record in self._runs.values():
+            for take in record.state.takes:
+                if take.id == take_id:
+                    return take
+        if self._store is not None:
+            return self._store.find_take(take_id)
+        return None
+
+    def publish(self, record: RunRecord, event: RunEvent | None) -> None:
+        loop = self._loop
+        if loop is None:
+            return
+        if not self._should_stream(record, event, time.monotonic()):
+            return
+        for queue in list(record.subscribers):
+            loop.call_soon_threadsafe(queue.put_nowait, event)
+
+    def _should_stream(self, record: RunRecord, event: RunEvent | None, now: float) -> bool:
+        """Coalesce progress ticks; node_done, terminal events, and the finish sentinel pass."""
+        if isinstance(event, ProgressEvent):
+            if now - record.last_progress < _MIN_PROGRESS_INTERVAL:
+                return False
+            record.last_progress = now
+        return True
+
+    def _execute(self, graph: Graph, target: str, record: RunRecord) -> None:
+        ctx = ExecutionContext(
+            run_id=record.state.run_id,
+            policy=self._policy,
+            emitter=_BroadcastEmitter(self, record),
+            cancel=record.cancel,
+        )
+        Executor(self._registry, self._cache).run(graph, target, ctx, record.state)
+        record.done = True
+        if self._store is not None:
+            self._store.update(record.state)
+        self.publish(record, None)
+
+
+def _historical(state: RunState) -> RunRecord:
+    """A finished run reloaded from the store: snapshot only, no live subscribers."""
+    record = RunRecord(state, CancelToken())
+    record.done = True
+    return record
+
+
+def _graph_hash(graph: Graph, target: str) -> str:
+    nodes = [
+        {
+            "id": node.id,
+            "type": node.type,
+            "params": node.params,
+            "inputs": {
+                port: [[e.from_node, e.output] for e in edges]
+                for port, edges in sorted(node.inputs.items())
+            },
+        }
+        for node in graph.nodes
+    ]
+    payload = json.dumps({"target": target, "nodes": nodes}, sort_keys=True, default=str)
+    return hashlib.sha256(payload.encode()).hexdigest()

inline_core/server/rpc.py

@@ -0,0 +1,60 @@
+"""The Studio app-backend on Core: the browser SPA speaks the InlineStudioApi wire protocol —
+``POST /rpc`` with ``{channel, args}`` plus an ``/events`` WebSocket, returning the same ``Result``
+envelope (``{"ok": true, "value": ...}`` / ``{"ok": false, "error": ...}``). Core is the sole
+backend; every channel is handled natively (the former proxy to the legacy Node backend is gone).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+#: A native channel handler: receives the positional args list, returns the value to wrap in Ok.
+Handler = Callable[[list[Any]], Awaitable[Any]]
+
+
+class RpcRouter:
+    """Routes an RPC channel to its native handler."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, Handler] = {}
+
+    def register(self, channel: str, handler: Handler) -> None:
+        self._handlers[channel] = handler
+
+    def has(self, channel: str) -> bool:
+        return channel in self._handlers
+
+    async def dispatch(self, channel: str, args: list[Any]) -> dict[str, Any]:
+        handler = self._handlers.get(channel)
+        if handler is None:
+            return {"ok": False, "error": f"No handler registered for channel {channel!r}."}
+        try:
+            return {"ok": True, "value": await handler(args)}
+        except Exception as error:  # noqa: BLE001 — Result envelope: errors never cross raw
+            return {"ok": False, "error": str(error)}
+
+
+class EventBroadcaster:
+    """Fans server→client event frames out to every connected ``/events`` WebSocket subscriber.
+
+    Native handlers push ``{"channel": ..., "payload": ...}`` frames here (matching the Node
+    broadcaster's shape); each open socket drains its own queue. Bridging the legacy Node event
+    stream is wired in with the fal domain (Part B4)."""
+
+    def __init__(self) -> None:
+        self._subscribers: set[asyncio.Queue[dict[str, Any]]] = set()
+
+    def add(self) -> asyncio.Queue[dict[str, Any]]:
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self._subscribers.add(queue)
+        return queue
+
+    def remove(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        self._subscribers.discard(queue)
+
+    def broadcast(self, channel: str, payload: Any) -> None:
+        frame = {"channel": channel, "payload": payload}
+        for queue in self._subscribers:
+            queue.put_nowait(frame)