[KM-715] charts: GET /charts by message_id only + tri-state status marker

Lead review round: lookup drops analysis_id (message_id is server-minted UUID,
globally unique); every response is HTTP 200 with status success|empty|
not_found + a human message. empty vs not_found is decided against the turn's
message_traceability row (PK lookup), so not_found reliably means "no completed
turn". Needs the additive idx_message_charts_message index (contract DDL note).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/api/v1/charts.py

@@ -1,18 +1,24 @@
 """Charts endpoint — user-facing chart retrieval for one turn (S2 visualization,
 SPINE_V2_PLAN §4.4/§4.5).
 
-`GET /api/v1/charts?analysis_id=&message_id=` returns every chart a `render_chart`
-tool call produced during one assistant turn, as `dataeyond.chart.v1` envelopes
+`GET /api/v1/charts?message_id=` returns every chart a `render_chart` tool call
+produced during one assistant turn, as `dataeyond.chart.v1` envelopes
 (SPINE_V2_PLAN §4.2). Rows are written by the chat pipeline right before the `done`
-SSE event; the FE fires this GET on `done`.
+SSE event; the FE fires this GET on `done` with the `message_id` from that event.
+Lookup is by `message_id` alone (Python-minted UUID4 — lead decision 2026-07-13).
 
-Unlike `GET /api/v1/traceability`, an **empty list is a valid 200** here (most turns
-don't ask for a chart) rather than a 404 — once `done` has fired there is no "not
-ready yet" state to distinguish from "no charts this turn".
+Every response is HTTP 200 with an explicit `status` marker (lead ask 2026-07-13):
+  - `success`   — ≥1 chart; render them.
+  - `empty`     — the turn completed but produced no charts (the common case).
+  - `not_found` — no completed turn is known for this message_id (mistyped/stale
+                  id, or an error turn — those never write a row). Distinguished
+                  from `empty` via the turn's traceability row.
 
 No auth — Go fronts Python.
 """
 
+from typing import Literal
+
 from fastapi import APIRouter, Query
 from pydantic import BaseModel
 
@@ -28,6 +34,8 @@ _store = PostgresChartStore()
 
 
 class ChartsResponse(BaseModel):
+    status: Literal["success", "empty", "not_found"]
+    message: str
     count: int
     charts: list[ChartRecord]
 
@@ -35,12 +43,30 @@ class ChartsResponse(BaseModel):
 @router.get("/charts", response_model=ChartsResponse)
 @log_execution(logger)
 async def get_charts(
-    analysis_id: str = Query(..., description="Analysis/session id"),
     message_id: str = Query(
         ..., description="Assistant turn id, taken from the `done` SSE event"
     ),
 ) -> ChartsResponse:
-    """Fetch every chart for one turn. Empty list (not 404) when the turn produced
-    none — the FE can call this unconditionally on every `done`."""
-    charts = await _store.list_for_message(analysis_id, message_id)
-    return ChartsResponse(count=len(charts), charts=charts)
+    """Fetch every chart for one turn. Always 200 — the `status` field carries the
+    outcome, so the FE can call this unconditionally on every `done`."""
+    charts = await _store.list_for_message(message_id)
+    if charts:
+        return ChartsResponse(
+            status="success",
+            message=f"{len(charts)} chart(s) for this message.",
+            count=len(charts),
+            charts=charts,
+        )
+    if await _store.turn_exists(message_id):
+        return ChartsResponse(
+            status="empty",
+            message="This message completed without producing charts.",
+            count=0,
+            charts=[],
+        )
+    return ChartsResponse(
+        status="not_found",
+        message="No completed turn is known for this message_id.",
+        count=0,
+        charts=[],
+    )

src/charts/store.py

@@ -27,7 +27,7 @@ from pydantic import BaseModel
 from sqlalchemy import select
 
 from src.db.postgres.connection import AsyncSessionLocal
-from src.db.postgres.models import MessageChartRow
+from src.db.postgres.models import MessageChartRow, MessageTraceabilityRow
 from src.middlewares.logging import get_logger
 
 logger = get_logger("charts_store")
@@ -48,7 +48,10 @@ class ChartStore(Protocol):
     """Persist + read `render_chart` outputs for one assistant `message_id`.
 
     `save` must never raise on the caller's path. `list_for_message` returns every
-    chart for one turn (possibly empty — a turn need not have asked for a chart).
+    chart for one turn (possibly empty — a turn need not have asked for a chart);
+    the lookup is by `message_id` alone (Python-minted UUID4, globally unique —
+    lead decision 2026-07-13). `turn_exists` says whether the turn flushed a
+    traceability row, so the endpoint can tell "no charts" from "unknown id".
     """
 
     async def save(
@@ -61,9 +64,9 @@ class ChartStore(Protocol):
         envelope: dict,
     ) -> None: ...
 
-    async def list_for_message(
-        self, analysis_id: str, message_id: str
-    ) -> list[ChartRecord]: ...
+    async def list_for_message(self, message_id: str) -> list[ChartRecord]: ...
+
+    async def turn_exists(self, message_id: str) -> bool: ...
 
 
 class NullChartStore:
@@ -84,11 +87,12 @@ class NullChartStore:
             chart_type=envelope.get("chart_type", "unknown"),
         )
 
-    async def list_for_message(
-        self, analysis_id: str, message_id: str
-    ) -> list[ChartRecord]:
+    async def list_for_message(self, message_id: str) -> list[ChartRecord]:
         return []
 
+    async def turn_exists(self, message_id: str) -> bool:
+        return False
+
 
 class PostgresChartStore:
     """Writes/reads `message_charts` rows. One insert per chart (not an upsert)."""
@@ -129,16 +133,15 @@ class PostgresChartStore:
                 error=str(exc),
             )
 
-    async def list_for_message(
-        self, analysis_id: str, message_id: str
-    ) -> list[ChartRecord]:
+    async def list_for_message(self, message_id: str) -> list[ChartRecord]:
+        # message_id-only lookup (lead decision 2026-07-13). NOTE for the Harry
+        # migration: the manual DDL's composite index (analysis_id, message_id)
+        # does not serve this predicate — an additive index on (message_id) is
+        # part of the handoff.
         async with AsyncSessionLocal() as session:
             result = await session.execute(
                 select(MessageChartRow)
-                .where(
-                    MessageChartRow.analysis_id == analysis_id,
-                    MessageChartRow.message_id == message_id,
-                )
+                .where(MessageChartRow.message_id == message_id)
                 .order_by(MessageChartRow.created_at)
             )
             rows = result.scalars().all()
@@ -152,3 +155,18 @@ class PostgresChartStore:
             )
             for row in rows
         ]
+
+    async def turn_exists(self, message_id: str) -> bool:
+        """True iff the turn flushed its traceability row (written before `done`).
+
+        Lets the endpoint tri-state a zero-chart GET: `empty` (completed turn, no
+        charts — the common case) vs `not_found` (unknown/mistyped id, or an error
+        turn, which never writes traceability). PK lookup — cheap.
+        """
+        async with AsyncSessionLocal() as session:
+            result = await session.execute(
+                select(MessageTraceabilityRow.message_id).where(
+                    MessageTraceabilityRow.message_id == message_id
+                )
+            )
+            return result.scalar_one_or_none() is not None