feat(realism): synthetic-files browser API

Adds GET /api/v1/realism/synthetic-files (paginated list, filters by
decky_uuid, persona, content_class) and
GET /api/v1/realism/synthetic-files/{uuid} (single row with last_body
and a truncated:bool flag set when the stored body is at the 64KB cap).

Repo gains count_synthetic_files() and get_synthetic_file(uuid). The
list view drops last_body to keep the wire payload bounded; the detail
endpoint is the only path that returns it. Read-only — orchestrator
remains the sole writer.

decnet/web/db/repository.py

@@ -1130,16 +1130,35 @@ class BaseRepository(ABC):
         *,
         decky_uuid: Optional[str] = None,
         persona: Optional[str] = None,
+        content_class: Optional[str] = None,
         limit: int = 100,
         offset: int = 0,
     ) -> list[dict[str, Any]]:
         """Paginated synthetic_files newest-first.
 
-        Optional filters narrow to one decky and/or one persona, used by
-        the dashboard's "files this decky has grown" view.
+        Optional filters narrow to one decky, persona, and/or content
+        class — used by the dashboard's "files this decky has grown"
+        view.
         """
         raise NotImplementedError
 
+    async def count_synthetic_files(
+        self,
+        *,
+        decky_uuid: Optional[str] = None,
+        persona: Optional[str] = None,
+        content_class: Optional[str] = None,
+    ) -> int:
+        """Total synthetic_files matching the same filters as
+        :meth:`list_synthetic_files`. Used to drive paginated UI."""
+        raise NotImplementedError
+
+    async def get_synthetic_file(
+        self, uuid: str,
+    ) -> Optional[dict[str, Any]]:
+        """Single synthetic_files row by uuid, or ``None``."""
+        raise NotImplementedError
+
     async def pick_random_synthetic_file_for_edit(
         self,
         decky_uuid: str,

decnet/web/db/sqlmodel_repo.py

@@ -3365,6 +3365,7 @@ class SQLModelRepository(BaseRepository):
         *,
         decky_uuid: Optional[str] = None,
         persona: Optional[str] = None,
+        content_class: Optional[str] = None,
         limit: int = 100,
         offset: int = 0,
     ) -> list[dict[str, Any]]:
@@ -3374,6 +3375,8 @@ class SQLModelRepository(BaseRepository):
                 stmt = stmt.where(SyntheticFile.decky_uuid == decky_uuid)
             if persona is not None:
                 stmt = stmt.where(SyntheticFile.persona == persona)
+            if content_class is not None:
+                stmt = stmt.where(SyntheticFile.content_class == content_class)
             stmt = (
                 stmt.order_by(desc(SyntheticFile.last_modified))
                 .offset(offset)
@@ -3382,6 +3385,36 @@ class SQLModelRepository(BaseRepository):
             result = await session.execute(stmt)
             return [r.model_dump(mode="json") for r in result.scalars().all()]
 
+    async def count_synthetic_files(
+        self,
+        *,
+        decky_uuid: Optional[str] = None,
+        persona: Optional[str] = None,
+        content_class: Optional[str] = None,
+    ) -> int:
+        from sqlalchemy import func as _f
+        async with self._session() as session:
+            stmt = select(_f.count(SyntheticFile.uuid))
+            if decky_uuid is not None:
+                stmt = stmt.where(SyntheticFile.decky_uuid == decky_uuid)
+            if persona is not None:
+                stmt = stmt.where(SyntheticFile.persona == persona)
+            if content_class is not None:
+                stmt = stmt.where(SyntheticFile.content_class == content_class)
+            result = await session.execute(stmt)
+            return int(result.scalar() or 0)
+
+    async def get_synthetic_file(
+        self, uuid: str,
+    ) -> Optional[dict[str, Any]]:
+        async with self._session() as session:
+            stmt = select(SyntheticFile).where(SyntheticFile.uuid == uuid)
+            result = await session.execute(stmt)
+            row = result.scalars().first()
+            if row is None:
+                return None
+            return row.model_dump(mode="json")
+
     async def pick_random_synthetic_file_for_edit(
         self,
         decky_uuid: str,

decnet/web/router/__init__.py

@@ -32,6 +32,7 @@ from .campaigns.api_events import router as campaign_events_router
 from .orchestrator.api_list_events import router as orchestrator_list_router
 from .orchestrator.api_events import router as orchestrator_events_router
 from .realism.api_personas import router as realism_personas_router
+from .realism.api_synthetic_files import router as realism_synthetic_files_router
 from .transcripts import transcripts_router
 from .config.api_get_config import router as config_get_router
 from .config.api_update_config import router as config_update_router
@@ -115,6 +116,7 @@ api_router.include_router(orchestrator_events_router)
 # "Persona Generation" page.  The orchestrator reads from the same
 # on-disk JSON file directly (see decnet.realism.personas_pool).
 api_router.include_router(realism_personas_router)
+api_router.include_router(realism_synthetic_files_router)
 
 # Observability
 api_router.include_router(stats_router)

decnet/web/router/realism/api_synthetic_files.py

@@ -0,0 +1,99 @@
+"""GET ``/api/v1/realism/synthetic-files`` — browse planted realism files.
+
+The orchestrator's realism worker grows synthetic files on each decky
+(notes, TODOs, drafts, scripts, log lines, canary artifacts). The
+:class:`~decnet.web.db.models.realism.SyntheticFile` table is the
+canonical record of what's been planted where; this endpoint lets
+operators inspect the lineage without ssh'ing into a decky.
+
+Read-only. No writes — the orchestrator is the sole writer; the
+dashboard is observation surface only.
+
+The body preview (``last_body``) is repo-clipped at 64 KB
+(:data:`SYNTHETIC_FILE_BODY_LIMIT`); when the original was larger the
+detail response carries ``truncated: true`` so the operator knows what
+they're looking at.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from decnet.telemetry import traced as _traced
+from decnet.web.db.models.realism import SYNTHETIC_FILE_BODY_LIMIT
+from decnet.web.dependencies import repo, require_viewer
+
+router = APIRouter()
+
+
+@router.get(
+    "/realism/synthetic-files",
+    tags=["Realism"],
+    responses={
+        401: {"description": "Could not validate credentials"},
+        403: {"description": "Insufficient permissions"},
+        422: {"description": "Validation error"},
+    },
+)
+@_traced("api.realism.list_synthetic_files")
+async def list_synthetic_files(
+    limit: int = Query(50, ge=1, le=500),
+    offset: int = Query(0, ge=0, le=2147483647),
+    decky_uuid: Optional[str] = Query(None, max_length=64),
+    persona: Optional[str] = Query(None, max_length=128),
+    content_class: Optional[str] = Query(None, max_length=32),
+    user: dict = Depends(require_viewer),
+) -> dict[str, Any]:
+    """Paginated synthetic_files newest-first.
+
+    Filters: ``decky_uuid``, ``persona``, ``content_class``. The list
+    response strips ``last_body`` to keep the payload bounded — fetch
+    the detail endpoint for the body preview.
+    """
+    rows = await repo.list_synthetic_files(
+        decky_uuid=decky_uuid,
+        persona=persona,
+        content_class=content_class,
+        limit=limit,
+        offset=offset,
+    )
+    total = await repo.count_synthetic_files(
+        decky_uuid=decky_uuid,
+        persona=persona,
+        content_class=content_class,
+    )
+    # The list view doesn't need bodies; drop them so the response stays
+    # small even when 50 rows each carry ~64 KB. Detail endpoint returns
+    # the body.
+    for r in rows:
+        r.pop("last_body", None)
+    return {"total": total, "limit": limit, "offset": offset, "data": rows}
+
+
+@router.get(
+    "/realism/synthetic-files/{uuid}",
+    tags=["Realism"],
+    responses={
+        401: {"description": "Could not validate credentials"},
+        403: {"description": "Insufficient permissions"},
+        404: {"description": "Synthetic file not found"},
+    },
+)
+@_traced("api.realism.get_synthetic_file")
+async def get_synthetic_file(
+    uuid: str,
+    user: dict = Depends(require_viewer),
+) -> dict[str, Any]:
+    """Return one synthetic_files row including the body preview.
+
+    ``truncated`` is true when the stored body is at the cap — the
+    decky filesystem holds the canonical bytes; the master view is a
+    snapshot.
+    """
+    row = await repo.get_synthetic_file(uuid)
+    if row is None:
+        raise HTTPException(status_code=404, detail="synthetic file not found")
+    body = row.get("last_body") or ""
+    row["truncated"] = len(body) >= SYNTHETIC_FILE_BODY_LIMIT
+    return row

tests/api/realism/test_synthetic_files_api.py

@@ -0,0 +1,146 @@
+"""GET /api/v1/realism/synthetic-files — paginated browser API."""
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi import HTTPException
+
+from decnet.web.db.models.realism import SYNTHETIC_FILE_BODY_LIMIT
+
+
+def _row(**over):
+    base = {
+        "uuid": "sf-1",
+        "decky_uuid": "d-1",
+        "path": "/home/admin/notes.txt",
+        "persona": "admin",
+        "content_class": "note",
+        "created_at": "2026-04-27T10:00:00+00:00",
+        "last_modified": "2026-04-27T10:00:00+00:00",
+        "edit_count": 0,
+        "content_hash": "deadbeef" * 8,
+        "last_body": "hello world",
+    }
+    base.update(over)
+    return base
+
+
+@pytest.mark.asyncio
+async def test_list_returns_paginated_envelope():
+    from decnet.web.router.realism.api_synthetic_files import (
+        list_synthetic_files,
+    )
+
+    rows = [_row(uuid=f"sf-{i}") for i in range(3)]
+    with patch(
+        "decnet.web.router.realism.api_synthetic_files.repo"
+    ) as mock_repo:
+        mock_repo.list_synthetic_files = AsyncMock(return_value=rows)
+        mock_repo.count_synthetic_files = AsyncMock(return_value=3)
+
+        result = await list_synthetic_files(
+            limit=50, offset=0,
+            decky_uuid=None, persona=None, content_class=None,
+            user={"uuid": "u", "role": "viewer"},
+        )
+
+    assert result["total"] == 3
+    assert result["limit"] == 50
+    assert result["offset"] == 0
+    assert len(result["data"]) == 3
+    # List view drops the body to keep the payload small.
+    for r in result["data"]:
+        assert "last_body" not in r
+
+
+@pytest.mark.asyncio
+async def test_list_forwards_filters_to_repo():
+    from decnet.web.router.realism.api_synthetic_files import (
+        list_synthetic_files,
+    )
+
+    with patch(
+        "decnet.web.router.realism.api_synthetic_files.repo"
+    ) as mock_repo:
+        mock_repo.list_synthetic_files = AsyncMock(return_value=[])
+        mock_repo.count_synthetic_files = AsyncMock(return_value=0)
+
+        await list_synthetic_files(
+            limit=10, offset=20,
+            decky_uuid="d-7", persona="alice", content_class="todo",
+            user={"uuid": "u", "role": "viewer"},
+        )
+
+    mock_repo.list_synthetic_files.assert_awaited_once_with(
+        decky_uuid="d-7", persona="alice", content_class="todo",
+        limit=10, offset=20,
+    )
+    mock_repo.count_synthetic_files.assert_awaited_once_with(
+        decky_uuid="d-7", persona="alice", content_class="todo",
+    )
+
+
+@pytest.mark.asyncio
+async def test_get_detail_returns_body_with_truncated_false():
+    from decnet.web.router.realism.api_synthetic_files import (
+        get_synthetic_file,
+    )
+
+    with patch(
+        "decnet.web.router.realism.api_synthetic_files.repo"
+    ) as mock_repo:
+        mock_repo.get_synthetic_file = AsyncMock(return_value=_row(
+            last_body="short body",
+        ))
+
+        result = await get_synthetic_file(
+            uuid="sf-1",
+            user={"uuid": "u", "role": "viewer"},
+        )
+
+    assert result["last_body"] == "short body"
+    assert result["truncated"] is False
+
+
+@pytest.mark.asyncio
+async def test_get_detail_marks_truncated_when_at_cap():
+    from decnet.web.router.realism.api_synthetic_files import (
+        get_synthetic_file,
+    )
+
+    body = "X" * SYNTHETIC_FILE_BODY_LIMIT
+    with patch(
+        "decnet.web.router.realism.api_synthetic_files.repo"
+    ) as mock_repo:
+        mock_repo.get_synthetic_file = AsyncMock(return_value=_row(
+            last_body=body,
+        ))
+
+        result = await get_synthetic_file(
+            uuid="sf-1",
+            user={"uuid": "u", "role": "viewer"},
+        )
+
+    assert len(result["last_body"]) == SYNTHETIC_FILE_BODY_LIMIT
+    assert result["truncated"] is True
+
+
+@pytest.mark.asyncio
+async def test_get_detail_404_when_missing():
+    from decnet.web.router.realism.api_synthetic_files import (
+        get_synthetic_file,
+    )
+
+    with patch(
+        "decnet.web.router.realism.api_synthetic_files.repo"
+    ) as mock_repo:
+        mock_repo.get_synthetic_file = AsyncMock(return_value=None)
+
+        with pytest.raises(HTTPException) as exc:
+            await get_synthetic_file(
+                uuid="missing",
+                user={"uuid": "u", "role": "viewer"},
+            )
+
+    assert exc.value.status_code == 404

tests/realism/test_synthetic_files_repo.py

@@ -114,3 +114,39 @@ async def test_pick_random_returns_eligible_row(repo):
     assert picked is not None
     assert picked["content_class"] == "todo"
     assert picked["path"] == "/home/admin/TODO.md"
+
+
+@pytest.mark.asyncio
+async def test_count_synthetic_files_respects_filters(repo):
+    await repo.record_synthetic_file(_row(decky="d1", path="/a", cls="todo"))
+    await repo.record_synthetic_file(_row(decky="d1", path="/b", cls="note"))
+    await repo.record_synthetic_file(_row(decky="d2", path="/c", cls="todo"))
+    assert await repo.count_synthetic_files() == 3
+    assert await repo.count_synthetic_files(decky_uuid="d1") == 2
+    assert await repo.count_synthetic_files(content_class="todo") == 2
+    assert await repo.count_synthetic_files(
+        decky_uuid="d1", content_class="note",
+    ) == 1
+
+
+@pytest.mark.asyncio
+async def test_list_filters_by_content_class(repo):
+    await repo.record_synthetic_file(_row(decky="d1", path="/a", cls="todo"))
+    await repo.record_synthetic_file(_row(decky="d1", path="/b", cls="note"))
+    rows = await repo.list_synthetic_files(content_class="todo")
+    assert len(rows) == 1
+    assert rows[0]["content_class"] == "todo"
+
+
+@pytest.mark.asyncio
+async def test_get_synthetic_file_returns_row(repo):
+    uuid = await repo.record_synthetic_file(_row(decky="d1", path="/a"))
+    got = await repo.get_synthetic_file(uuid)
+    assert got is not None
+    assert got["uuid"] == uuid
+    assert got["path"] == "/a"
+
+
+@pytest.mark.asyncio
+async def test_get_synthetic_file_returns_none_when_missing(repo):
+    assert await repo.get_synthetic_file("does-not-exist") is None