feat(chat): durable internal tool trace persistence

[ABB65]

Summary

Before this PR the chat loop stored exactly two rows per POST — user prompt and final assistant message — collapsing every multi-iteration tool turn into a flat row pair. Intermediate assistant narration was dropped; tool_result blocks were never persisted at all. Resume reads couldn't reconstruct the Anthropic-protocol shape Claude saw on prior turns, so multi-iteration conversations effectively lost their tool history once the request ended.

This PR persists the full protocol-replay trace under a single turn_id per POST while keeping the user-facing transcript clean.

Schema (migration 009)

ALTER TABLE messages
  ADD content_blocks jsonb NULL           -- structured Anthropic blocks
  ADD turn_id uuid NOT NULL               -- groups all rows from one POST
  ADD turn_sequence smallint NOT NULL     -- deterministic order in batch
  ADD iteration smallint NULL             -- engine iteration counter
  ADD internal boolean NOT NULL DEFAULT false

RLS rewrite (the security boundary):

SELECT  internal = false AND user owns conversation
INSERT  internal = false AND user owns conversation

Service-role queries bypass RLS and load the full trace. This is defense-in-depth — a stray client query OR a buggy route forgetting includeInternal: false cannot leak internal rows.

Persistence shape per POST

• 1 seed user row — internal=false, iteration=NULL, turn_sequence=0
• N assistant rows — internal=true for intermediate iterations, internal=false for the final one
• 0..N tool_result rows — internal=true, role='user' (matches Anthropic protocol where tool_results are sent as user messages)
• All share one turn_id; turn_sequence increments per row
• Token columns land only on the final visible assistant row (Anthropic returns per-call totals, not per-iteration)

Turn-safe history budget — the protocol-critical change

The old row-level cutoff could drop an assistant tool_use block while keeping its matching tool_result (or vice-versa); Anthropic rejects orphaned tool_use blocks and silently drifts on orphaned tool_result. The walker now:

1. Groups rows by turn_id preserving DB order
2. Walks groups newest → oldest summing per-group estimates
3. Drops ENTIRE turns at the budget boundary — never half
4. If the DB row limit truncated mid-turn (rare), drops the leading partial group

Legacy rows (no turn_id) fall back to single-row "turns" — protocol-safe by definition since they never carried tool blocks.

Provider surface

• MessageInsertInput exposes new columns + internal
• insertMessages(rows[]) — single batched INSERT, one round-trip instead of N, atomic at the batch level
• loadConversationMessages(..., { includeInternal }) — defaults false; resume paths set true

Quota — UNCHANGED

agent_usage.message_count and api_message_usage.message_count still increment exactly once per POST via the existing reservation step. Multiple persisted rows do NOT bill the user multiple messages. Trace persistence is Contentrain-side observability/replay, not customer-facing metering.

Test plan

• pnpm typecheck clean
• pnpm lint — 0 errors on changed files
• pnpm test — 622 passed (618 + 4 new)
  • db: trace row shape (seed user + assistant + tool_result under one turn_id), single batched insertMessages call, intermediate rows internal=true / final internal=false, cache token landing on final, Conversation API symmetric path
  • conversation-history: content_blocks priority over legacy columns; turn-grouped budget keeps whole multi-row turns together; older turns dropped whole when budget overflows
  • chat-route integration: resume passes includeInternal: true; saveChatResult receives iterations array instead of the old assistantText/assistantContent pair

Out of scope (separate follow-ups)

• Backfill of pre-009 rows. Pre-launch system, no real data; legacy rows live as single-row turns under the new walker.
• block_kind discriminator column. Discriminator lives inside each block's type; partial indexes can grow when there's a real query pattern.
• Per-iteration token breakdown. Provider returns per-call totals only.
• UI rendering of tool_use chips. Data is there; UI can adapt at its own pace.

Diff stat

11 files changed, +684 / −137. Migration + 4 new unit tests + 1 new integration assertion.