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