From dbd9af42e9fac60035ed1cf9723524ce861e6c33 Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Sun, 7 Jun 2026 19:06:44 +0530
Subject: [PATCH 1/4] docs(spec): playground messages redesign

Captures the brainstormed design for the playground redesign:

- prompt_version.template -> template_messages jsonb (replace, with one
  release of legacy column for safe deploy/rollback)
- system + human messages only for v1; AI/tools/output_schema deferred
- Jinja {{ var }} substitution kept; no f-string selector
- single prompt panel; compare deferred to its own iteration
- save creates a new version always; "New prompt..." entry in the
  picker handles the unloaded case
- empty variables render as empty string

Spec covers schema migration, request/response contracts,
web composer rewrite, dispatcher changes, error semantics, testing
strategy, and a 4-step rollout that lets each PR land independently.

Signed-off-by: Gaurav Dubey <gauravdubey0107@gmail.com>
Signed-off-by: gaurav0107 <gauravdubey0107@gmail.com>
---
 ...-07-playground-messages-redesign-design.md | 276 ++++++++++++++++++
 1 file changed, 276 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-07-playground-messages-redesign-design.md

diff --git a/docs/superpowers/specs/2026-06-07-playground-messages-redesign-design.md b/docs/superpowers/specs/2026-06-07-playground-messages-redesign-design.md
new file mode 100644
index 0000000..d1cb62f
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-07-playground-messages-redesign-design.md
@@ -0,0 +1,276 @@
+# Playground messages redesign
+
+**Status:** Draft
+**Owner:** mia
+**Date:** 2026-06-07
+
+## Why
+
+The playground today asks the user to compose a single text template and
+fill `{{ var }}` placeholders. That doesn't match how modern chat models
+are actually called: a typed list of messages where the system prompt and
+the user turn are separate things. The reference UX
+([LangSmith's playground][langsmith-pg]) shows what we want — typed
+messages, an Inputs panel that fills detected variables, save-as-prompt
+with versioning. PR #10 made the model picker honor configured
+credentials but left the playground's data shape untouched.
+
+[langsmith-pg]: https://docs.langchain.com/langsmith/playground
+
+## Decisions (locked in brainstorm)
+
+| # | Topic | Decision |
+|---|---|---|
+| 1 | Storage shape | Replace `prompt_version.template text` with `template_messages jsonb`. Backfill rewrites every existing row to `[{role: "human", content: <template>}]`. |
+| 2 | Message roles (v1) | `system` and `human` only. AI / tool / output_schema are deferred. |
+| 3 | Variable syntax | Jinja `{{ var }}`. No format selector. |
+| 4 | Compare mode | Deferred. Single prompt panel only. |
+| 5 | Save scope | Messages only. Model + temperature stay as runtime knobs on the playground request. |
+| 6 | Layout | Stacked. Prompt → Inputs → Output, full-width. |
+| 7 | Save behavior | Always creates a new version. Save on a loaded `v3` produces `v4`. |
+| 8 | Save (new prompt) | Prompt picker has a `New prompt…` option that surfaces an inline name+slug field. |
+| 9 | Empty variables | Render as empty string. No pre-flight block, no warning banner. |
+
+## Out of scope
+
+- Compare mode (two prompt panels, two outputs). Deferred to its own follow-up.
+- AI / tool / output_schema message types.
+- Streaming responses. Playground stays sync.
+- Editing the loaded prompt in place (always-new-version is the rule).
+- Per-prompt "recommended model" persistence (model is runtime-only).
+
+## Goals
+
+1. The playground composer renders System and Human messages as separate, typed editors.
+2. Variables in any message body show up in the Inputs panel with one row per `{{var}}`.
+3. Save creates a new `prompt_version` whose `template_messages` carries the structured shape; versioning is preserved.
+4. Existing prompts in production keep loading with no operator action.
+
+## Non-goals
+
+- We do not maintain wire-compatibility with the old `template text` field on the response. Clients reading prompts will get `template_messages` instead.
+
+## Architecture
+
+### Postgres schema (migration 0026)
+
+```sql
+alter table prompt_version
+    add column template_messages jsonb;
+
+-- Backfill existing rows.
+update prompt_version
+   set template_messages = jsonb_build_array(
+           jsonb_build_object('role', 'human', 'content', template)
+       )
+ where template_messages is null;
+
+alter table prompt_version
+    alter column template_messages set not null;
+
+-- The legacy column stays for one release as a back-reference.
+-- A follow-up migration drops it once we've confirmed the new code path
+-- handles every consumer (api router, eval runner, studio playback).
+comment on column prompt_version.template is
+    'DEPRECATED — see template_messages. Drop after one release.';
+```
+
+We keep `template` for one release window so a rollback during the
+deploy can read the old data. Drop in a follow-up migration once
+production is stable.
+
+### Message structure
+
+```python
+class Message(BaseModel):
+    role: Literal["system", "human"]
+    content: str  # may contain {{ var }} placeholders
+```
+
+Stored as a JSON array. The order is significant — it's the order the
+messages reach the model. The renderer iterates the array and emits
+provider-specific message dicts (Anthropic / OpenAI / Gemini all accept
+`{"role": <r>, "content": <s>}` shapes; LiteLLM normalizes for us).
+
+### API contract
+
+**Prompt versions**
+
+`prompt_version.template` becomes optional in the response shape (kept
+during the one-release window). The new field is authoritative:
+
+```python
+class PromptVersionOut(BaseModel):
+    id: UUID
+    prompt_id: UUID
+    version: int
+    template_messages: list[Message]
+    template: str | None  # legacy; populated from template_messages[0].content
+                          # when there's exactly one human message and no system
+    input_schema: dict | None
+    model_params: dict | None
+    aliases: list[str]
+    commit_message: str | None
+    created_at: datetime
+```
+
+`POST /v1/prompts/{prompt_id}/versions` accepts `template_messages`
+(required) and ignores `template` if also sent. The
+`commit_message` is optional, populated from the playground's "Save"
+flow.
+
+**Playground runs**
+
+The request body shape changes:
+
+```python
+class PlaygroundCreate(BaseModel):
+    project_id: UUID
+    prompt_version_id: UUID | None = None
+    raw_messages: list[Message] | None = None  # was: raw_template: str | None
+    variables: dict[str, Any]
+    model: str
+    temperature: float | None
+    max_tokens: int | None
+```
+
+Exactly one of `prompt_version_id` or `raw_messages` is required (same
+xor as today). The renderer:
+
+```python
+def render_messages(messages: list[Message], vars: dict) -> list[Message]:
+    return [
+        Message(role=m.role, content=jinja_render(m.content, vars))
+        for m in messages
+    ]
+```
+
+The dispatcher hands the rendered list to LiteLLM verbatim (no
+single-string compaction).
+
+**Old field retained for one release** — the request still accepts
+`raw_template` and wraps it as `[{"role": "human", "content": <s>}]`
+internally. Old clients keep working until we drop the column.
+
+### Web UI
+
+`web/src/components/PlaygroundClient.tsx` rewires the composer:
+
+- State shape:
+  ```ts
+  type Message = { role: "system" | "human"; content: string };
+  const [messages, setMessages] = useState<Message[]>([
+    { role: "system", content: "" },
+    { role: "human", content: "" },
+  ]);
+  ```
+- Each message renders in its own card with: a role pill (clickable
+  dropdown to switch system↔human), a content `<textarea>` that
+  auto-grows, reorder ↑↓ buttons, delete ×, and a tiny variable
+  highlight overlay.
+- "+ Add message" button at the bottom of the prompt panel inserts a new
+  empty human message.
+- Variable detection: regex `/\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g`
+  over each message content. The Inputs panel shows the deduped union.
+  An Input value that no longer matches a detected variable stays in
+  state but is hidden from the panel; if the var reappears the value
+  re-attaches.
+- Save: if `loadedPrompt` is null, "Save" opens an inline `name + slug`
+  input pair (slug auto-derived from name on first keystroke); on submit
+  posts `POST /v1/prompts` then `POST /v1/prompts/{id}/versions`. If
+  `loadedPrompt` is non-null, posts `POST /v1/prompts/{id}/versions`
+  directly — that endpoint always creates the next version number,
+  EXCEPT when the messages are byte-identical to the most recent version
+  (server short-circuits and returns the existing row; UI surfaces "no
+  changes since v{n}").
+- The role pill is a 2-option dropdown (`system` / `human`) for v1. If
+  AI is added later, this widens; nothing else about the composer
+  changes.
+
+### Worker / dispatcher
+
+`services/api/tracebility_api/routers/playground.py` swaps:
+
+- `_render_template(template, vars)` → `_render_messages(messages, vars)`
+  returning a list of dicts.
+- The dispatch call (`gateway.dispatch(...)`) now passes
+  `messages=rendered_messages` instead of constructing a single
+  `[{"role": "user", "content": rendered}]`. The gateway already
+  accepts a list (LiteLLM's `completion(messages=[...])`); we were
+  collapsing it for no reason.
+- `playground_session.rendered_prompt text` is kept and set to a
+  human-readable join of the rendered messages (for the trace view).
+  The structured form is in the new column described next.
+
+`alter table playground_session add column rendered_messages jsonb;`
+populated alongside `rendered_prompt`. Read paths can prefer the
+structured form.
+
+### Trace view (no change required)
+
+The run still writes `inputs` as the rendered system+human concatenation
+(the worker's existing path for `playground_session`). The trace at
+`/runs/{id}` doesn't need to know about the structured shape; it's a
+display-time concern. We can render messages explicitly later as a
+follow-up.
+
+## Data flow
+
+```
+[ web composer ]                        [ api ]                          [ litellm ]
+  messages: list -- POST /playground/runs ----> render Jinja per msg ---> dispatch(messages=[...])
+                                              \                                        |
+                                               -- write playground_session row         v
+                                                  rendered_messages jsonb              llm
+                                                  rendered_prompt text                  |
+                                                                                       result
+                                              <-- worker writes run + span <-----------/
+```
+
+## Errors
+
+- **Template render failure** (Jinja syntax error in a saved prompt) →
+  `500` with `error.code = "template_render_error"` plus the offending
+  Jinja error text. Today's behavior. We surface it on the row.
+- **Empty variable** → renders as empty string. No error.
+- **Save when prompt is unloaded and no name supplied** → 400 with a
+  field-level error from the inline form. The button is disabled until
+  the name field has at least 2 chars; that's the primary defense.
+- **Save when current messages would produce a no-op version (identical
+  to last version)** → server returns the existing version, doesn't
+  create a duplicate. UI shows "no changes since v{n}".
+
+## Testing
+
+- **Unit (api):** `_render_messages` over a 2-message prompt with one
+  variable — verify variables get substituted in both system and human.
+  Round-trip a `Message` through the migration backfill — old `template`
+  becomes `[{role: "human", content: <same>}]`.
+- **Unit (web):** detect-variables regex over a multi-message array;
+  duplicate variables across messages dedupe to one input row; deleting
+  the only message containing `{{ tx }}` removes the row.
+- **Integration:** a `POST /v1/playground/runs` with
+  `raw_messages = [system, human-with-{{x}}]` and `variables = {"x":
+  "y"}` produces a session whose `rendered_messages` matches and whose
+  output is the model's response. Existing tests around the
+  `raw_template` path stay green via the back-compat wrapper.
+- **Migration:** smoke against staging — every existing
+  `prompt_version` row picks up `template_messages` with the wrap shape.
+
+## Rollout
+
+1. Land the migration first as a separate PR (additive only;
+   deployable independently). Backfill in the same migration.
+2. Land the api change in a second PR — accepts both `raw_template` and
+   `raw_messages`, prefers messages when both are present.
+3. Land the web change in a third PR — composer rewrite, save flow.
+   Ship behind no flag; the api back-compat covers any race.
+4. After one release window: drop the legacy `template` column,
+   remove the `raw_template` accept path. Separate cleanup PR.
+
+## Open items
+
+- Whether to render system + human in `playground_session.rendered_prompt`
+  with `<system>...</system>\n<human>...</human>` delimiters or a plain
+  newline-join. Going with plain join (`\n\n`) for v1; the structured
+  form in `rendered_messages` is the source of truth for replay.

From d5d18af47f585f4ab8add5cb1602352599d08ed5 Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Sun, 7 Jun 2026 19:23:56 +0530
Subject: [PATCH 2/4] feat(schema/pg): 0026 prompt_version.template_messages

Replace the single-string template with a structured list of typed
messages so the playground can compose system + human turns. Backfills
every existing row to [{role: 'human', content: <old template>}],
preserving exact behavior for prompts in production. Legacy 'template'
column kept for one release as a deploy/rollback safety net.

Companion to docs/superpowers/specs/2026-06-07-playground-messages-redesign-design.md.

Signed-off-by: Gaurav Dubey <gauravdubey0107@gmail.com>
Signed-off-by: gaurav0107 <gauravdubey0107@gmail.com>
---
 .../0026_prompt_template_messages.sql         | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 schemas/postgres/migrations/0026_prompt_template_messages.sql

diff --git a/schemas/postgres/migrations/0026_prompt_template_messages.sql b/schemas/postgres/migrations/0026_prompt_template_messages.sql
new file mode 100644
index 0000000..3a5f52e
--- /dev/null
+++ b/schemas/postgres/migrations/0026_prompt_template_messages.sql
@@ -0,0 +1,44 @@
+-- 0026_prompt_template_messages.sql
+-- Replace the single-string `prompt_version.template` with a structured
+-- list of typed messages (system / human, with the door open for ai/tool
+-- later). The legacy `template` column is kept for one release as a
+-- deploy/rollback safety net; a follow-up migration drops it.
+--
+-- Backfill: every existing row becomes
+--     [{"role": "human", "content": <old template>}]
+-- which preserves single-message prompt behavior verbatim. Variable
+-- syntax stays Jinja {{ var }} — same renderer, same wire format on
+-- the LiteLLM dispatch side.
+
+begin;
+
+alter table prompt_version
+    add column template_messages jsonb;
+
+update prompt_version
+   set template_messages = jsonb_build_array(
+           jsonb_build_object('role', 'human', 'content', template)
+       )
+ where template_messages is null;
+
+alter table prompt_version
+    alter column template_messages set not null;
+
+-- The legacy column is now redundant. Keep it for one release window
+-- so a rollback can read the old shape; a follow-up migration drops it.
+comment on column prompt_version.template is
+    'DEPRECATED: replaced by template_messages. Drop after one release.';
+
+-- Cheap structural guard: every row's template_messages must be a
+-- non-empty jsonb array. The check is structural-only; role-value
+-- validation lives at the application layer (matches how we validate
+-- other jsonb columns like quota_period.attributes).
+alter table prompt_version
+    add constraint prompt_version_template_messages_nonempty
+    check (jsonb_typeof(template_messages) = 'array'
+           and jsonb_array_length(template_messages) > 0);
+
+insert into schema_migrations (version) values ('0026_prompt_template_messages')
+on conflict (version) do nothing;
+
+commit;

From 0cb9868c5f21c2e9848bfeea5b55af4511a88579 Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Sun, 7 Jun 2026 19:32:20 +0530
Subject: [PATCH 3/4] feat(api): expose prompt_version.template_messages
 alongside legacy template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the structured Message model (system | human) and exposes both
fields on PromptVersionOut so the playground (Plan B) and the web UI
(Plan C) can read the new shape while existing clients keep seeing the
legacy single-string field. The legacy field is derived from
template_messages and is empty when the prompt has more than one
message or any system message — better than lying.

The router's hydration is centralized in _hydrate_version so the three
SELECT paths share one row->model conversion.

Companion to docs/superpowers/specs/2026-06-07-playground-messages-redesign-design.md.

Signed-off-by: gaurav0107 <gauravdubey0107@gmail.com>
---
 .../tests/unit/test_prompt_response_shape.py  | 138 ++++++++++++++++++
 .../api/tracebility_api/routers/prompts.py    |  72 +++++++--
 2 files changed, 195 insertions(+), 15 deletions(-)
 create mode 100644 services/api/tests/unit/test_prompt_response_shape.py

diff --git a/services/api/tests/unit/test_prompt_response_shape.py b/services/api/tests/unit/test_prompt_response_shape.py
new file mode 100644
index 0000000..82e43f4
--- /dev/null
+++ b/services/api/tests/unit/test_prompt_response_shape.py
@@ -0,0 +1,138 @@
+"""Prompt response models surface both `template` and `template_messages`.
+
+The new field is authoritative; the legacy `template` is derived for one
+release of back-compat. After the release window we drop the legacy field.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from datetime import UTC, datetime
+from uuid import uuid4
+
+import pytest
+from pydantic import ValidationError
+
+# These imports refer to symbols added in this task. Until the
+# implementation lands, the test fails at import time.
+from tracebility_api.routers.prompts import (
+    Message,
+    PromptVersionOut,
+    _hydrate_version,
+)
+
+
+def _now():
+    return datetime.now(UTC)
+
+
+def test_response_carries_template_messages_and_legacy_template_derived():
+    """A single-human-message version round-trips with both fields.
+
+    `template` is derived from the messages array; clients that only know
+    about the legacy field still work.
+    """
+    msg = Message(role="human", content="hello {{ x }}")
+    out = PromptVersionOut(
+        id=uuid4(),
+        prompt_id=uuid4(),
+        version=1,
+        template_messages=[msg],
+        template="hello {{ x }}",
+        input_schema=None,
+        model_params=None,
+        aliases=[],
+        commit_message=None,
+        created_at=_now(),
+    )
+    assert out.template_messages == [msg]
+    assert out.template == "hello {{ x }}"
+
+
+def test_response_with_system_and_human_omits_legacy_template():
+    """A multi-message version sets `template` to '' rather than picking one.
+
+    Old clients see an empty template — better than misleading them with
+    the human content alone.
+    """
+    out = PromptVersionOut(
+        id=uuid4(),
+        prompt_id=uuid4(),
+        version=2,
+        template_messages=[
+            Message(role="system", content="be terse"),
+            Message(role="human", content="answer {{ q }}"),
+        ],
+        template="",
+        input_schema=None,
+        model_params=None,
+        aliases=[],
+        commit_message=None,
+        created_at=_now(),
+    )
+    assert len(out.template_messages) == 2
+    assert out.template == ""
+
+
+def test_message_role_is_constrained_to_v1_set():
+    """Pydantic enforces role in {system, human}. AI/tool not yet supported."""
+    Message(role="system", content="ok")
+    Message(role="human", content="ok")
+    with pytest.raises(ValidationError):
+        Message(role="ai", content="not yet")
+
+
+# ---------------------------------------------------------------------------
+# _hydrate_version derivation rule. The above tests pin the model shape;
+# these pin the row -> model conversion logic so a regression in the
+# legacy-template derivation actually fails CI.
+# ---------------------------------------------------------------------------
+
+
+def _row(messages):
+    """Build a fake asyncpg.Record-shaped dict for _hydrate_version."""
+    return {
+        "id": uuid4(),
+        "prompt_id": uuid4(),
+        "version": 1,
+        "template_messages": messages,
+        "input_schema": None,
+        "model_params": None,
+        "aliases": [],
+        "commit_message": None,
+        "created_at": _now(),
+    }
+
+
+def test_hydrate_version_derives_template_from_single_human_message():
+    out = _hydrate_version(_row([{"role": "human", "content": "hello {{ x }}"}]))
+    assert out.template == "hello {{ x }}"
+    assert out.template_messages == [Message(role="human", content="hello {{ x }}")]
+
+
+def test_hydrate_version_empty_template_for_multi_message():
+    out = _hydrate_version(
+        _row(
+            [
+                {"role": "system", "content": "be terse"},
+                {"role": "human", "content": "answer {{ q }}"},
+            ]
+        )
+    )
+    assert out.template == ""
+
+
+def test_hydrate_version_empty_template_for_single_system_message():
+    """A single system message is the rare-but-real case where the legacy
+    field can't be derived. Empty string, not the system content."""
+    out = _hydrate_version(_row([{"role": "system", "content": "be terse"}]))
+    assert out.template == ""
+
+
+def test_hydrate_version_handles_jsonb_string_form():
+    """Some asyncpg paths return jsonb as a string; _hydrate_version
+    coerces defensively."""
+    raw = _json.dumps([{"role": "human", "content": "hi"}])
+    out = _hydrate_version(_row(raw))
+    assert out.template_messages == [Message(role="human", content="hi")]
+    assert out.template == "hi"
diff --git a/services/api/tracebility_api/routers/prompts.py b/services/api/tracebility_api/routers/prompts.py
index 68fafbc..7585878 100644
--- a/services/api/tracebility_api/routers/prompts.py
+++ b/services/api/tracebility_api/routers/prompts.py
@@ -19,7 +19,7 @@
 import json as _json
 import re
 from datetime import datetime
-from typing import Any
+from typing import Any, Literal
 from uuid import UUID
 
 import asyncpg
@@ -62,10 +62,28 @@ class PromptPatch(BaseModel):
     description: str | None = Field(default=None, max_length=2000)
 
 
+class Message(BaseModel):
+    """A single typed message in a prompt template.
+
+    v1 supports `system` and `human` roles. AI / tool / output_schema are
+    deferred — see the spec for the rationale and the deferral triggers.
+    The content is a Jinja `{{ var }}` template; substitution happens at
+    render time on the playground / dispatch path.
+    """
+
+    role: Literal["system", "human"]
+    content: str
+
+
 class PromptVersionOut(BaseModel):
     id: UUID
     prompt_id: UUID
     version: int
+    template_messages: list[Message]
+    # Legacy single-string field. Populated for back-compat with clients
+    # written before plan B lands. Derived from `template_messages` when
+    # the version is exactly one human message; otherwise empty string.
+    # Drop after one release per the migration cleanup plan.
     template: str
     input_schema: dict[str, Any] | None
     model_params: dict[str, Any] | None
@@ -283,15 +301,15 @@ async def list_versions(
     )
     rows = await pool.fetch(
         """
-        select id, prompt_id, version, template, input_schema, model_params,
-               aliases, commit_message, created_at
+        select id, prompt_id, version, template, template_messages,
+               input_schema, model_params, aliases, commit_message, created_at
         from prompt_version
         where prompt_id = $1
         order by version desc
         """,
         prompt_id,
     )
-    return PromptVersionList(versions=[_version_from_row(r) for r in rows])
+    return PromptVersionList(versions=[_hydrate_version(r) for r in rows])
 
 
 @router.post(
@@ -345,8 +363,9 @@ async def create_version(
                     aliases, commit_message, created_by
                 )
                 values ($1, $2, $3, $4::jsonb, $5::jsonb, $6, $7, $8)
-                returning id, prompt_id, version, template, input_schema,
-                          model_params, aliases, commit_message, created_at
+                returning id, prompt_id, version, template, template_messages,
+                          input_schema, model_params, aliases, commit_message,
+                          created_at
                 """,
             prompt_id,
             next_version,
@@ -362,7 +381,7 @@ async def create_version(
             prompt_id,
         )
     assert row is not None
-    version = _version_from_row(row)
+    version = _hydrate_version(row)
     await audit.record(
         pool,
         principal=principal,
@@ -398,8 +417,8 @@ async def get_version(
     )
     row = await pool.fetchrow(
         """
-        select id, prompt_id, version, template, input_schema, model_params,
-               aliases, commit_message, created_at
+        select id, prompt_id, version, template, template_messages,
+               input_schema, model_params, aliases, commit_message, created_at
         from prompt_version
         where prompt_id = $1 and version = $2
         """,
@@ -408,7 +427,7 @@ async def get_version(
     )
     if row is None:
         raise HTTPException(status.HTTP_404_NOT_FOUND, "version not found")
-    return _version_from_row(row)
+    return _hydrate_version(row)
 
 
 @router.post("/{prompt_id}/aliases", response_model=PromptVersionOut)
@@ -453,8 +472,9 @@ async def assign_alias(
                     else aliases || array[$2]
                 end
                 where prompt_id = $1 and version = $3
-                returning id, prompt_id, version, template, input_schema,
-                          model_params, aliases, commit_message, created_at
+                returning id, prompt_id, version, template, template_messages,
+                          input_schema, model_params, aliases, commit_message,
+                          created_at
                 """,
             prompt_id,
             body.alias,
@@ -465,7 +485,7 @@ async def assign_alias(
             prompt_id,
         )
     assert row is not None
-    version = _version_from_row(row)
+    version = _hydrate_version(row)
     await audit.record(
         pool,
         principal=principal,
@@ -501,13 +521,35 @@ def _normalize_aliases(raw: list[str]) -> list[str]:
     return out
 
 
-def _version_from_row(row: asyncpg.Record) -> PromptVersionOut:
+def _hydrate_version(row: asyncpg.Record) -> PromptVersionOut:
+    """Convert a prompt_version row to the response model.
+
+    Reads template_messages (the canonical structured field) and derives
+    the legacy `template` for one release of back-compat — only populated
+    when the version is exactly one bare human message; otherwise empty
+    so old clients see a cleanly-empty value rather than a half-truth.
+    """
     data = dict(row)
+    msgs_raw = data["template_messages"]
+    # asyncpg normally returns jsonb already decoded (here always a list),
+    # but some driver/codec configurations hand back the raw json string —
+    # decode defensively so we never feed a str into model_validate.
+    if isinstance(msgs_raw, str):
+        msgs_raw = _json.loads(msgs_raw)
+    # Unknown roles raise ValidationError by design: v1 only persists
+    # {system, human}, and silently widening the Literal would mask a
+    # data-corruption bug. If/when ai/tool roles land, extend Message,
+    # don't loosen this validation.
+    messages = [Message.model_validate(m) for m in msgs_raw]
+    legacy_template = (
+        messages[0].content if len(messages) == 1 and messages[0].role == "human" else ""
+    )
     return PromptVersionOut(
         id=data["id"],
         prompt_id=data["prompt_id"],
         version=data["version"],
-        template=data["template"],
+        template_messages=messages,
+        template=legacy_template,
         input_schema=_jsonb(data.get("input_schema")),
         model_params=_jsonb(data.get("model_params")),
         aliases=list(data.get("aliases") or []),

From 5e836f40f9c47ac3bbb989213078c16bd5067dfc Mon Sep 17 00:00:00 2001
From: gaurav0107 <gauravdubey0107@gmail.com>
Date: Sun, 7 Jun 2026 19:43:31 +0530
Subject: [PATCH 4/4] test(prompts): integration check for template_messages
 backfill

Pins the post-migration invariants - column exists NOT NULL, existing
rows have the [{role: human, content: <old template>}] wrap shape, and
the check constraint refuses an empty messages array. Skips cleanly
when the local db has no prompts to inspect.

Signed-off-by: gaurav0107 <gauravdubey0107@gmail.com>
---
 .../test_prompts_template_messages.py         | 124 ++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 services/api/tests/integration/test_prompts_template_messages.py

diff --git a/services/api/tests/integration/test_prompts_template_messages.py b/services/api/tests/integration/test_prompts_template_messages.py
new file mode 100644
index 0000000..8967c28
--- /dev/null
+++ b/services/api/tests/integration/test_prompts_template_messages.py
@@ -0,0 +1,124 @@
+"""Post-migration invariants for prompt_version.template_messages.
+
+Boots an asyncpg pool against the live local docker postgres and pins:
+  1. The column exists, is jsonb, and is NOT NULL.
+  2. Existing rows have the [{role: human, content: <old template>}]
+     wrap shape from migration 0026's backfill.
+  3. The non-empty-array CHECK constraint refuses an empty array insert.
+
+Skips cleanly when postgres is unreachable, when prompt_version is
+empty, or when there are no project rows to FK against. The end-to-end
+HTTP-level check (request body shape, etc.) lands in Plan B.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+
+import asyncpg
+import pytest
+
+
+def _reachable(host: str, port: int) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=0.25):
+            return True
+    except OSError:
+        return False
+
+
+_DEFAULT_LOCAL_DSN = "postgres://tracebility:tracebility@localhost:5432/tracebility"
+# `services/api/tests/conftest.py` setdefaults TRACEBILITY_PG_DSN to a unit-test
+# sentinel ("postgres://test/test") so config.load() doesn't raise at import.
+# Treat that sentinel as "unset" for integration purposes and fall back to the
+# local docker default; an explicit TRACEBILITY_TEST_DSN still wins.
+PG_DSN = (
+    os.environ.get("TRACEBILITY_TEST_DSN")
+    or (
+        os.environ.get("TRACEBILITY_PG_DSN")
+        if os.environ.get("TRACEBILITY_PG_DSN") not in (None, "postgres://test/test")
+        else None
+    )
+    or _DEFAULT_LOCAL_DSN
+)
+
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.fixture
+async def pg_pool():
+    if not _reachable("localhost", 5432):
+        pytest.skip("postgres not reachable")
+    pool = await asyncpg.create_pool(PG_DSN, min_size=1, max_size=2)
+    try:
+        yield pool
+    finally:
+        await pool.close()
+
+
+async def test_template_messages_column_exists_and_is_not_null(pg_pool):
+    """Direct schema check; the migration runner ran in setup."""
+    row = await pg_pool.fetchrow(
+        """
+        select column_name, data_type, is_nullable
+          from information_schema.columns
+         where table_name = 'prompt_version'
+           and column_name = 'template_messages'
+        """
+    )
+    assert row is not None
+    assert row["data_type"] == "jsonb"
+    assert row["is_nullable"] == "NO"
+
+
+async def test_existing_rows_have_human_wrapped_messages(pg_pool):
+    """If there are existing prompt_version rows in the local db, every
+    one has the wrap shape from the backfill. Skip cleanly if empty."""
+    rows = await pg_pool.fetch("select template, template_messages from prompt_version limit 5")
+    if not rows:
+        pytest.skip("prompt_version is empty on this db; backfill is a no-op")
+    for r in rows:
+        msgs = r["template_messages"]
+        # asyncpg may decode jsonb to dict/list directly or to str; handle both.
+        if isinstance(msgs, str):
+            msgs = json.loads(msgs)
+        assert isinstance(msgs, list) and len(msgs) >= 1
+        assert msgs[0]["role"] == "human"
+        assert msgs[0]["content"] == r["template"]
+
+
+async def test_constraint_blocks_empty_array(pg_pool):
+    """The check constraint refuses an empty list (every prompt has at
+    least one message). Wrapped in a transaction we always roll back so
+    nothing leaks if the worker is killed mid-test."""
+    project_row = await pg_pool.fetchrow("select id from project where deleted_at is null limit 1")
+    if project_row is None:
+        pytest.skip("no project rows on this db; cannot insert prompt")
+    project_id = project_row["id"]
+
+    async with pg_pool.acquire() as conn:
+        tx = conn.transaction()
+        await tx.start()
+        try:
+            prompt_id = await conn.fetchval(
+                """
+                insert into prompt (project_id, slug, name)
+                values ($1, 'test-' || md5(random()::text), 'test')
+                returning id
+                """,
+                project_id,
+            )
+            with pytest.raises(asyncpg.CheckViolationError):
+                await conn.execute(
+                    """
+                    insert into prompt_version
+                      (prompt_id, version, template, template_messages)
+                    values ($1, 1, '', '[]'::jsonb)
+                    """,
+                    prompt_id,
+                )
+        finally:
+            await tx.rollback()