Resolve Issue #60

apps/api/alembic/versions/f7a8b9c0d1e2_add_agentic_workflow_trace_columns.py

@@ -0,0 +1,46 @@
+"""add agentic workflow trace columns
+
+Revision ID: f7a8b9c0d1e2
+Revises: f6a7b8c9d0e1
+Create Date: 2026-05-14 03:20:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "f7a8b9c0d1e2"
+down_revision: Union[str, Sequence[str], None] = "f6a7b8c9d0e1"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "retrieval_runs",
+        sa.Column("parent_run_id", sa.String(length=36), nullable=True),
+    )
+    op.add_column(
+        "retrieval_runs",
+        sa.Column("workflow_step_id", sa.String(length=64), nullable=True),
+    )
+    op.add_column(
+        "retrieval_runs",
+        sa.Column("workflow_plan", sa.JSON(), nullable=True),
+    )
+    op.create_index(
+        "ix_retrieval_runs_parent_run_id",
+        "retrieval_runs",
+        ["parent_run_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_retrieval_runs_parent_run_id", table_name="retrieval_runs")
+    op.drop_column("retrieval_runs", "workflow_plan")
+    op.drop_column("retrieval_runs", "workflow_step_id")
+    op.drop_column("retrieval_runs", "parent_run_id")

apps/api/tests/contract/test_agentic_answer_policy_contract.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import pytest
+
+from shared.services.retrieval.agentic.policy import attempt_answer
+from shared.services.retrieval.agentic.types import AgentRunConfig, AgentState
+
+
+async def _malformed_json_wrapper(_prompt: str) -> str:
+    return '{"status": "DONE", "answer": "truncated"'
+
+
+@pytest.mark.asyncio
+async def test_attempt_answer_should_not_expose_malformed_json_wrapper() -> None:
+    status, answer, reason = await attempt_answer(
+        _malformed_json_wrapper,
+        query="What changed?",
+        evidence_text="┈ evidence",
+        state=AgentState(),
+        config=AgentRunConfig(),
+    )
+
+    assert status == "NOT_FOUND"
+    assert answer == ""
+    assert reason == "attempt_answer returned malformed JSON"

apps/api/tests/migrations/test_schema_contract.py

@@ -233,3 +233,26 @@ def test_api_standalone_mode_should_create_auth_user_table_before_migrations(
         "updatedAt",
     }.issubset(columns)
     assert email_unique_count == 1
+
+
+def test_agentic_retrieval_trace_schema_matches_orm(migrated_head_engine: Engine) -> None:
+    with migrated_head_engine.begin() as connection:
+        run_columns = set(
+            connection.execute(
+                text(
+                    """
+                    SELECT column_name
+                    FROM information_schema.columns
+                    WHERE table_name = 'retrieval_runs'
+                    """
+                )
+            )
+            .scalars()
+            .all()
+        )
+
+    assert {
+        "parent_run_id",
+        "workflow_step_id",
+        "workflow_plan",
+    }.issubset(run_columns)