Media dtypes: image, audio and video as narrowed artifact references

A port may now declare `image`, `audio` or `video`. Each is the artifact
reference the engine already had, narrowed by the `media_type` on it, so a
speech recogniser declares what it eats rather than taking any bytes at all and
finding out. Bytes still never travel as a message and nothing on the wire
stops being JSON: a camera publishes one reference per frame, a microphone one
per chunk, and a reference may carry a `meta` dict nothing here interprets.

Streaming media is therefore an ordinary streaming port — with one change to
what that means. An emission used to journal an item with no payload, so
downstream read whatever was current when the item was claimed; a consumer
slower than its producer saw only the newest chunk and the ones between were
lost. That is right for a training curve and wrong for a second of speech, so
an emission now journals a `kind="emission"` item carrying its values, and the
executor hands them to the nodes reading that message instead of writing them
to state again. The value in state stays the latest, which is what everything
else reads, and the wave is filtered by what actually changed rather than
walking everything reachable. No queue serialization change — the existing
`outputs` field carries it.

Continuous media makes the store's missing GC a real problem, so this closes
it: `sweep_artifacts` runs hourly, keeps every digest a `run_artifact` row
records or a live message holds, spares anything written in the last hour, and
stands aside entirely while a run is in flight, since a node may store a
checkpoint long before it returns the reference to it. That also collects the
orphans a deleted flow has always left behind. `ARTIFACT_GC_INTERVAL_S=0` turns
it off.

Around the edges: `GET /artifacts/{digest}` serves the media type the caller
passes and answers ranged requests, so a browser plays a clip rather than
downloading it; `PUT` spools to disk instead of holding the whole body in
memory, as does `save_artifact` given a path; a Media widget draws whatever its
message points at, and a wall panel may fetch the bytes its own tiles are
showing and nothing else; and a connector gets `save_artifact`, for a device
whose readings are bytes.

What this cannot do is live video: a frame every second or two is a glance, and
the honest answer above that is the camera's own stream, which the widget takes
as a URL and the browser plays from source.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

backend/fluksio/api/deps.py

@@ -15,6 +15,7 @@ from fluksio.core import security
 from fluksio.core.config import settings
 from fluksio.core.db import engine
 from fluksio.flow import panels
+from fluksio.flow.artifacts import is_reference
 from fluksio.flow.controller import FlowController
 from fluksio.flow.dashboards import DashboardStore
 from fluksio.flow.workers import PythonWorkerPool
@@ -78,13 +79,36 @@ def _panel_messages(panel_id: str, request: Request) -> set[str]:
     return panels.messages_for(panel_id, store)
 
 
+def _panel_digests(panel_id: str, request: Request) -> set[str]:
+    """The artifacts this panel's messages are pointing at right now.
+
+    A media tile fetches the bytes its message names, so the messages already
+    bounding the panel bound this too — one step further along, through
+    whatever those messages currently hold.
+    """
+    controller: FlowController | None = getattr(
+        request.app.state, "flow_controller", None
+    )
+    if controller is None:
+        return set()
+    names = _panel_messages(panel_id, request)
+    if not names:
+        return set()
+    found: set[str] = set()
+    for value in controller.state.get_present(sorted(names)).values():
+        if is_reference(value):
+            found.add(str(value["digest"]))
+    return found
+
+
 def _panel_may(payload: dict[str, Any], request: Request) -> None:
     """Refuse anything a wall panel has no business asking for.
 
     A panel credential names the account that approved the pairing, so without
     this it would be that person's session hanging on a wall. What a panel
     genuinely needs is small and worth writing out: the dashboards it was
-    assigned, its own definition, and the messages its own widgets bind to.
+    assigned, its own definition, the messages its own widgets bind to, and the
+    bytes those messages currently point at, for a tile drawing a camera frame.
 
     Publishing is in the list because a panel cannot be strictly read-only — a
     control on a panel is the point of putting one there, and a querying chart
@@ -128,6 +152,13 @@ def _panel_may(payload: dict[str, Any], request: Request) -> None:
         else:
             name = ""
         allowed = bool(name) and name in _panel_messages(panel.id, request)
+    elif method == "GET" and path.startswith(f"{api}/artifacts/"):
+        # The bytes behind a media message a tile on this panel is drawing.
+        # Scoped to what those messages hold *now*, which is exactly what a
+        # live widget asks for — a screen has no business reading an artifact
+        # off an old run because it happens to know the digest.
+        digest = unquote(path[len(f"{api}/artifacts/") :])
+        allowed = "/" not in digest and digest in _panel_digests(panel.id, request)
 
     if not allowed:
         raise HTTPException(

backend/fluksio/api/routes/artifacts.py

@@ -5,19 +5,28 @@ worker cannot — and having one path rather than two is what keeps a flow's
 code the same wherever it runs.
 """
 
+import re
+import tempfile
+from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from fastapi.responses import StreamingResponse
+from fastapi.responses import FileResponse
 from jwt.exceptions import InvalidTokenError
 from pydantic import BaseModel
 from sqlmodel import Session
+from starlette.concurrency import run_in_threadpool
 
 from fluksio.api.deps import user_from_token
 from fluksio.core import security
 from fluksio.core.db import engine
 from fluksio.flow.artifacts import ArtifactStore
 
+#: What may be echoed back as a response content type. The caller holds the
+#: reference and passes its media type, so this guards a header rather than
+#: trusting one — anything else is served as bytes.
+_MEDIA_TYPE = re.compile(r"^[\w.+-]+/[\w.+-]+$")
+
 
 def artifact_caller(request: Request) -> str:
     """Who may move artifacts: a signed-in person, or an attached worker.
@@ -71,21 +80,45 @@ async def put_artifact(
     name: str = Query(default=""),
     media_type: str = Query(default=""),
 ) -> Any:
-    """Store the request body and answer with the reference to it."""
+    """Store the request body and answer with the reference to it.
+
+    Spooled to disk as it arrives rather than buffered: a video segment is as
+    legitimate a body here as a checkpoint, and neither should have to fit in
+    memory twice.
+    """
     store = _store(request)
-    body = await request.body()
-    return store.put([body], name=name, media_type=media_type)
+    handle = tempfile.NamedTemporaryFile(dir=store.root, delete=False)
+    try:
+        with handle:
+            async for chunk in request.stream():
+                handle.write(chunk)
+        return await run_in_threadpool(
+            store.put_file, Path(handle.name), media_type, name
+        )
+    finally:
+        Path(handle.name).unlink(missing_ok=True)
 
 
 @router.get("/{digest}")
-def get_artifact(digest: str, request: Request) -> Any:
-    """Stream one artifact back."""
+def get_artifact(
+    digest: str, request: Request, media_type: str = Query(default="")
+) -> Any:
+    """Serve one artifact back.
+
+    The caller passes the media type off the reference it holds, which is what
+    lets a browser play a clip rather than download it; the store itself keeps
+    only bytes. Ranged requests are answered because an audio or video element
+    scrubbing through a file asks for them.
+    """
     store = _store(request)
     path = store.path(digest)
     if path is None:
         raise HTTPException(status_code=404, detail="No such artifact")
-    return StreamingResponse(
-        store.read(digest),
-        media_type="application/octet-stream",
-        headers={"Content-Length": str(path.stat().st_size)},
+    return FileResponse(
+        path,
+        media_type=(
+            media_type if _MEDIA_TYPE.match(media_type) else "application/octet-stream"
+        ),
+        # The digest is the content, so it is also the perfect validator.
+        headers={"ETag": f'"{digest}"'},
     )