@jami-studio/core 0.92.25 → 0.92.27

package/corpus/core/src/observability/store.ts

@@ -1,1321 +1,1313 @@
-/**
- * SQL persistence for the agent observability system.
- *
- * Creates and manages tables for traces, feedback, evals, experiments,
- * and satisfaction scores. Follows the same raw-SQL pattern as
- * run-store.ts and usage/store.ts — framework tables use getDbExec()
- * rather than Drizzle ORM (which is for template-level schemas).
- */
-import {
-  getDbExec,
-  intType,
-  isPostgres,
-  retryOnDdlRace,
-} from "../db/client.js";
-import {
-  ensureTableExists,
-  ensureColumnExists,
-  ensureIndexExists,
-} from "../db/ddl-guard.js";
-import { isDuplicateColumnError } from "../db/migrations.js";
-import type {
-  TraceSpan,
-  TraceSummary,
-  FeedbackEntry,
-  SatisfactionScore,
-  EvalResult,
-  EvalDataset,
-  Experiment,
-  ExperimentAssignment,
-  ExperimentMetricResult,
-} from "./types.js";
-
-function safeJsonParse<T>(value: unknown, fallback: T): T {
-  if (!value) return fallback;
-  try {
-    return JSON.parse(String(value));
-  } catch {
-    return fallback;
-  }
-}
-
-// Tables whose rows are owned by an end user — drives the boot-time
-// user_id ALTER loop and the per-user composite indexes below. Every
-// new user-owned observability table must be added here so the upgrade
-// path and the per-user query plan stay in sync.
-const USER_SCOPED_TABLES = [
-  "agent_trace_spans",
-  "agent_trace_summaries",
-  "agent_satisfaction_scores",
-  "agent_evals",
-  "agent_feedback",
-] as const;
-
-/**
- * Append an `AND user_id = ?` clause when a userId filter is requested.
- * Returns the fully-bound WHERE clause + args ready to splice into the
- * caller's SQL. Centralizes the pattern so tests can assert one shape.
- */
-function withUserFilter(
-  baseWhere: string,
-  baseArgs: any[],
-  userId: string | undefined,
-): { where: string; args: any[] } {
-  if (userId == null) return { where: baseWhere, args: baseArgs };
-  return {
-    where: `${baseWhere} AND user_id = ?`,
-    args: [...baseArgs, userId],
-  };
-}
-
-let _initPromise: Promise<void> | undefined;
-
-export async function ensureObservabilityTables(): Promise<void> {
-  if (!_initPromise) {
-    _initPromise = (async () => {
-      const client = getDbExec();
-
-      const traceSpansCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_trace_spans (
-          id TEXT PRIMARY KEY,
-          run_id TEXT NOT NULL,
-          thread_id TEXT,
-          user_id TEXT,
-          parent_span_id TEXT,
-          span_type TEXT NOT NULL,
-          name TEXT NOT NULL,
-          input_tokens ${intType()} NOT NULL DEFAULT 0,
-          output_tokens ${intType()} NOT NULL DEFAULT 0,
-          cache_read_tokens ${intType()} NOT NULL DEFAULT 0,
-          cache_write_tokens ${intType()} NOT NULL DEFAULT 0,
-          cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,
-          duration_ms ${intType()} NOT NULL DEFAULT 0,
-          status TEXT NOT NULL DEFAULT 'success',
-          error_message TEXT,
-          metadata TEXT,
-          created_at ${intType()} NOT NULL
-        )
-      `;
-
-      const traceSummariesCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_trace_summaries (
-          run_id TEXT PRIMARY KEY,
-          thread_id TEXT,
-          user_id TEXT,
-          total_spans ${intType()} NOT NULL DEFAULT 0,
-          llm_calls ${intType()} NOT NULL DEFAULT 0,
-          tool_calls ${intType()} NOT NULL DEFAULT 0,
-          successful_tools ${intType()} NOT NULL DEFAULT 0,
-          failed_tools ${intType()} NOT NULL DEFAULT 0,
-          total_duration_ms ${intType()} NOT NULL DEFAULT 0,
-          total_cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,
-          total_input_tokens ${intType()} NOT NULL DEFAULT 0,
-          total_output_tokens ${intType()} NOT NULL DEFAULT 0,
-          model TEXT NOT NULL DEFAULT '',
-          created_at ${intType()} NOT NULL
-        )
-      `;
-
-      const feedbackCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_feedback (
-          id TEXT PRIMARY KEY,
-          run_id TEXT,
-          thread_id TEXT,
-          message_seq ${intType()},
-          feedback_type TEXT NOT NULL,
-          value TEXT NOT NULL DEFAULT '',
-          user_id TEXT,
-          created_at ${intType()} NOT NULL
-        )
-      `;
-
-      const satisfactionScoresCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_satisfaction_scores (
-          id TEXT PRIMARY KEY,
-          thread_id TEXT NOT NULL,
-          user_id TEXT,
-          frustration_score REAL NOT NULL DEFAULT 0,
-          rephrasing_score REAL NOT NULL DEFAULT 0,
-          abandonment_score REAL NOT NULL DEFAULT 0,
-          sentiment_score REAL NOT NULL DEFAULT 0,
-          length_trend_score REAL NOT NULL DEFAULT 0,
-          computed_at ${intType()} NOT NULL
-        )
-      `;
-
-      const evalsCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_evals (
-          id TEXT PRIMARY KEY,
-          run_id TEXT NOT NULL,
-          thread_id TEXT,
-          user_id TEXT,
-          eval_type TEXT NOT NULL,
-          criteria TEXT NOT NULL,
-          score REAL NOT NULL DEFAULT 0,
-          reasoning TEXT,
-          metadata TEXT,
-          created_at ${intType()} NOT NULL
-        )
-      `;
-
-      const evalDatasetsCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_eval_datasets (
-          id TEXT PRIMARY KEY,
-          name TEXT NOT NULL,
-          description TEXT NOT NULL DEFAULT '',
-          entries TEXT NOT NULL DEFAULT '[]',
-          created_at ${intType()} NOT NULL,
-          updated_at ${intType()} NOT NULL
-        )
-      `;
-
-      const experimentsCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_experiments (
-          id TEXT PRIMARY KEY,
-          name TEXT NOT NULL,
-          status TEXT NOT NULL DEFAULT 'draft',
-          variants TEXT NOT NULL DEFAULT '[]',
-          metrics TEXT NOT NULL DEFAULT '[]',
-          assignment_level TEXT NOT NULL DEFAULT 'user',
-          started_at ${intType()},
-          ended_at ${intType()},
-          created_at ${intType()} NOT NULL,
-          owner_email TEXT
-        )
-      `;
-
-      const experimentAssignmentsCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_experiment_assignments (
-          experiment_id TEXT NOT NULL,
-          user_id TEXT NOT NULL,
-          variant_id TEXT NOT NULL,
-          assigned_at ${intType()} NOT NULL,
-          PRIMARY KEY (experiment_id, user_id)
-        )
-      `;
-
-      const experimentResultsCreateSql = `
-        CREATE TABLE IF NOT EXISTS agent_experiment_results (
-          id TEXT PRIMARY KEY,
-          experiment_id TEXT NOT NULL,
-          variant_id TEXT NOT NULL,
-          metric TEXT NOT NULL,
-          value REAL NOT NULL DEFAULT 0,
-          sample_size ${intType()} NOT NULL DEFAULT 0,
-          confidence_low REAL NOT NULL DEFAULT 0,
-          confidence_high REAL NOT NULL DEFAULT 0,
-          computed_at ${intType()} NOT NULL
-        )
-      `;
-
-      if (isPostgres()) {
-        // PG guard: probe → guarded DDL → re-probe; skips lock on already-migrated path
-        await ensureTableExists("agent_trace_spans", traceSpansCreateSql);
-        await ensureTableExists(
-          "agent_trace_summaries",
-          traceSummariesCreateSql,
-        );
-        await ensureTableExists("agent_feedback", feedbackCreateSql);
-        await ensureTableExists(
-          "agent_satisfaction_scores",
-          satisfactionScoresCreateSql,
-        );
-        await ensureTableExists("agent_evals", evalsCreateSql);
-        await ensureTableExists("agent_eval_datasets", evalDatasetsCreateSql);
-        await ensureTableExists("agent_experiments", experimentsCreateSql);
-        await ensureTableExists(
-          "agent_experiment_assignments",
-          experimentAssignmentsCreateSql,
-        );
-        await ensureTableExists(
-          "agent_experiment_results",
-          experimentResultsCreateSql,
-        );
-        await ensureColumnExists(
-          "agent_experiments",
-          "owner_email",
-          `ALTER TABLE agent_experiments ADD COLUMN IF NOT EXISTS owner_email TEXT`,
-        );
-        for (const table of USER_SCOPED_TABLES) {
-          await ensureColumnExists(
-            table,
-            "user_id",
-            `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS user_id TEXT`,
-          );
-        }
-        await ensureIndexExists(
-          "idx_trace_spans_run",
-          `CREATE INDEX IF NOT EXISTS idx_trace_spans_run ON agent_trace_spans (run_id)`,
-        );
-        await ensureIndexExists(
-          "idx_trace_spans_thread",
-          `CREATE INDEX IF NOT EXISTS idx_trace_spans_thread ON agent_trace_spans (thread_id)`,
-        );
-        await ensureIndexExists(
-          "idx_trace_spans_created",
-          `CREATE INDEX IF NOT EXISTS idx_trace_spans_created ON agent_trace_spans (created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_trace_summaries_created",
-          `CREATE INDEX IF NOT EXISTS idx_trace_summaries_created ON agent_trace_summaries (created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_trace_summaries_user",
-          `CREATE INDEX IF NOT EXISTS idx_trace_summaries_user ON agent_trace_summaries (user_id, created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_trace_spans_user",
-          `CREATE INDEX IF NOT EXISTS idx_trace_spans_user ON agent_trace_spans (user_id)`,
-        );
-        await ensureIndexExists(
-          "idx_feedback_thread",
-          `CREATE INDEX IF NOT EXISTS idx_feedback_thread ON agent_feedback (thread_id)`,
-        );
-        await ensureIndexExists(
-          "idx_feedback_created",
-          `CREATE INDEX IF NOT EXISTS idx_feedback_created ON agent_feedback (created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_feedback_user",
-          `CREATE INDEX IF NOT EXISTS idx_feedback_user ON agent_feedback (user_id, created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_satisfaction_thread",
-          `CREATE INDEX IF NOT EXISTS idx_satisfaction_thread ON agent_satisfaction_scores (thread_id)`,
-        );
-        await ensureIndexExists(
-          "idx_satisfaction_user",
-          `CREATE INDEX IF NOT EXISTS idx_satisfaction_user ON agent_satisfaction_scores (user_id, computed_at)`,
-        );
-        await ensureIndexExists(
-          "idx_evals_run",
-          `CREATE INDEX IF NOT EXISTS idx_evals_run ON agent_evals (run_id)`,
-        );
-        await ensureIndexExists(
-          "idx_evals_created",
-          `CREATE INDEX IF NOT EXISTS idx_evals_created ON agent_evals (created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_evals_user",
-          `CREATE INDEX IF NOT EXISTS idx_evals_user ON agent_evals (user_id, created_at)`,
-        );
-        await ensureIndexExists(
-          "idx_experiment_results_exp",
-          `CREATE INDEX IF NOT EXISTS idx_experiment_results_exp ON agent_experiment_results (experiment_id)`,
-        );
-        return;
-      }
-
-      // SQLite (local dev): no lock problem — keep the original behaviour.
-      await retryOnDdlRace(() => client.execute(traceSpansCreateSql));
-
-      await retryOnDdlRace(() => client.execute(traceSummariesCreateSql));
-
-      await retryOnDdlRace(() => client.execute(feedbackCreateSql));
-
-      await retryOnDdlRace(() => client.execute(satisfactionScoresCreateSql));
-
-      await retryOnDdlRace(() => client.execute(evalsCreateSql));
-
-      await retryOnDdlRace(() => client.execute(evalDatasetsCreateSql));
-
-      await retryOnDdlRace(() => client.execute(experimentsCreateSql));
-
-      // Additive migration for DBs created before the owner column shipped
-      // (any pre-existing rows have NULL owner — see `updateExperiment` for
-      // the migration semantics). Mutations on those rows fall back to the
-      // standard authentication gate but cannot enforce per-owner scoping
-      // until they're re-saved.
-      try {
-        await client.execute(
-          `ALTER TABLE agent_experiments ADD COLUMN owner_email TEXT`,
-        );
-      } catch {
-        // Column already exists — expected after first run.
-      }
-
-      await retryOnDdlRace(() =>
-        client.execute(experimentAssignmentsCreateSql),
-      );
-
-      await retryOnDdlRace(() => client.execute(experimentResultsCreateSql));
-
-      // Idempotent column upgrades for DBs created before per-user
-      // isolation. SQLite has no `ADD COLUMN IF NOT EXISTS`; Postgres
-      // surfaces "column ... already exists". `isDuplicateColumnError`
-      // (from db/migrations.ts) recognizes both shapes.
-      for (const table of USER_SCOPED_TABLES) {
-        try {
-          await client.execute(`ALTER TABLE ${table} ADD COLUMN user_id TEXT`);
-        } catch (err) {
-          if (isDuplicateColumnError(err)) continue;
-          throw err;
-        }
-      }
-
-      // Indexes for common query patterns
-      const indexes = [
-        `CREATE INDEX IF NOT EXISTS idx_trace_spans_run ON agent_trace_spans (run_id)`,
-        `CREATE INDEX IF NOT EXISTS idx_trace_spans_thread ON agent_trace_spans (thread_id)`,
-        `CREATE INDEX IF NOT EXISTS idx_trace_spans_created ON agent_trace_spans (created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_trace_summaries_created ON agent_trace_summaries (created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_trace_summaries_user ON agent_trace_summaries (user_id, created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_trace_spans_user ON agent_trace_spans (user_id)`,
-        `CREATE INDEX IF NOT EXISTS idx_feedback_thread ON agent_feedback (thread_id)`,
-        `CREATE INDEX IF NOT EXISTS idx_feedback_created ON agent_feedback (created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_feedback_user ON agent_feedback (user_id, created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_satisfaction_thread ON agent_satisfaction_scores (thread_id)`,
-        `CREATE INDEX IF NOT EXISTS idx_satisfaction_user ON agent_satisfaction_scores (user_id, computed_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_evals_run ON agent_evals (run_id)`,
-        `CREATE INDEX IF NOT EXISTS idx_evals_created ON agent_evals (created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_evals_user ON agent_evals (user_id, created_at)`,
-        `CREATE INDEX IF NOT EXISTS idx_experiment_results_exp ON agent_experiment_results (experiment_id)`,
-      ];
-      for (const sql of indexes) {
-        try {
-          await client.execute(sql);
-        } catch {
-          // Index might already exist
-        }
-      }
-    })().catch((err) => {
-      _initPromise = undefined;
-      throw err;
-    });
-  }
-  return _initPromise;
-}
-
-// ─── Trace span CRUD ─────────────────────────────────────────────────
-
-export async function insertTraceSpan(span: TraceSpan): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  await client.execute({
-    sql: `INSERT INTO agent_trace_spans
-      (id, run_id, thread_id, user_id, parent_span_id, span_type, name,
-       input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
-       cost_cents_x100, duration_ms, status, error_message, metadata, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    args: [
-      span.id,
-      span.runId,
-      span.threadId,
-      span.userId,
-      span.parentSpanId,
-      span.spanType,
-      span.name,
-      span.inputTokens,
-      span.outputTokens,
-      span.cacheReadTokens,
-      span.cacheWriteTokens,
-      span.costCentsX100,
-      span.durationMs,
-      span.status,
-      span.errorMessage,
-      span.metadata ? JSON.stringify(span.metadata) : null,
-      span.createdAt,
-    ],
-  });
-}
-
-export async function upsertTraceSummary(summary: TraceSummary): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  // user_id is intentionally NOT updated on conflict — once a run's
-  // owner is recorded it shouldn't change under us.
-  if (isPostgres()) {
-    await client.execute({
-      sql: `INSERT INTO agent_trace_summaries
-        (run_id, thread_id, user_id, total_spans, llm_calls, tool_calls,
-         successful_tools, failed_tools, total_duration_ms,
-         total_cost_cents_x100, total_input_tokens, total_output_tokens,
-         model, created_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT (run_id) DO UPDATE SET
-          total_spans = EXCLUDED.total_spans,
-          llm_calls = EXCLUDED.llm_calls,
-          tool_calls = EXCLUDED.tool_calls,
-          successful_tools = EXCLUDED.successful_tools,
-          failed_tools = EXCLUDED.failed_tools,
-          total_duration_ms = EXCLUDED.total_duration_ms,
-          total_cost_cents_x100 = EXCLUDED.total_cost_cents_x100,
-          total_input_tokens = EXCLUDED.total_input_tokens,
-          total_output_tokens = EXCLUDED.total_output_tokens,
-          model = EXCLUDED.model`,
-      args: [
-        summary.runId,
-        summary.threadId,
-        summary.userId,
-        summary.totalSpans,
-        summary.llmCalls,
-        summary.toolCalls,
-        summary.successfulTools,
-        summary.failedTools,
-        summary.totalDurationMs,
-        summary.totalCostCentsX100,
-        summary.totalInputTokens,
-        summary.totalOutputTokens,
-        summary.model,
-        summary.createdAt,
-      ],
-    });
-  } else {
-    await client.execute({
-      sql: `INSERT INTO agent_trace_summaries
-        (run_id, thread_id, user_id, total_spans, llm_calls, tool_calls,
-         successful_tools, failed_tools, total_duration_ms,
-         total_cost_cents_x100, total_input_tokens, total_output_tokens,
-         model, created_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT (run_id) DO UPDATE SET
-          total_spans = EXCLUDED.total_spans,
-          llm_calls = EXCLUDED.llm_calls,
-          tool_calls = EXCLUDED.tool_calls,
-          successful_tools = EXCLUDED.successful_tools,
-          failed_tools = EXCLUDED.failed_tools,
-          total_duration_ms = EXCLUDED.total_duration_ms,
-          total_cost_cents_x100 = EXCLUDED.total_cost_cents_x100,
-          total_input_tokens = EXCLUDED.total_input_tokens,
-          total_output_tokens = EXCLUDED.total_output_tokens,
-          model = EXCLUDED.model`,
-      args: [
-        summary.runId,
-        summary.threadId,
-        summary.userId,
-        summary.totalSpans,
-        summary.llmCalls,
-        summary.toolCalls,
-        summary.successfulTools,
-        summary.failedTools,
-        summary.totalDurationMs,
-        summary.totalCostCentsX100,
-        summary.totalInputTokens,
-        summary.totalOutputTokens,
-        summary.model,
-        summary.createdAt,
-      ],
-    });
-  }
-}
-
-/**
- * Purge trace spans, summaries, and eval results older than `cutoffMs`
- * (a Unix epoch in milliseconds — rows with `created_at < cutoffMs` are
- * deleted). Returns the per-table deletion counts. Satisfies the span
- * retention TTL noted in /tmp/security-audit/12-mcp-a2a-agent.md
- * (MEDIUM #14): trace metadata can hold sensitive tool inputs, so we
- * cap the storage horizon. Feedback rows are retained — they're
- * intentionally durable for product analytics. Experiments and
- * datasets are also retained because they are user-authored
- * configuration, not call telemetry.
- */
-export async function deleteOldTraceData(cutoffMs: number): Promise<{
-  spans: number;
-  summaries: number;
-  evals: number;
-}> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const cutoff = Math.floor(cutoffMs);
-
-  const [spansResult, summariesResult, evalsResult] = await Promise.all([
-    client.execute({
-      sql: `DELETE FROM agent_trace_spans WHERE created_at < ?`,
-      args: [cutoff],
-    }),
-    client.execute({
-      sql: `DELETE FROM agent_trace_summaries WHERE created_at < ?`,
-      args: [cutoff],
-    }),
-    client.execute({
-      sql: `DELETE FROM agent_evals WHERE created_at < ?`,
-      args: [cutoff],
-    }),
-  ]);
-
-  return {
-    spans: Number(spansResult.rowsAffected ?? 0),
-    summaries: Number(summariesResult.rowsAffected ?? 0),
-    evals: Number(evalsResult.rowsAffected ?? 0),
-  };
-}
-
-export async function getTraceSpansForRun(
-  runId: string,
-  opts: { userId?: string } = {},
-): Promise<TraceSpan[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { where, args } = withUserFilter("run_id = ?", [runId], opts.userId);
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_trace_spans WHERE ${where} ORDER BY created_at ASC`,
-    args,
-  });
-  return (rows as any[]).map(rowToTraceSpan);
-}
-
-export async function getTraceSummaries(opts: {
-  sinceMs?: number;
-  limit?: number;
-  userId?: string;
-}): Promise<TraceSummary[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const sinceMs = opts.sinceMs ?? 0;
-  const limit = opts.limit ?? 100;
-  const { where, args } = withUserFilter(
-    "created_at >= ?",
-    [sinceMs],
-    opts.userId,
-  );
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_trace_summaries
-      WHERE ${where}
-      ORDER BY created_at DESC
-      LIMIT ?`,
-    args: [...args, limit],
-  });
-  return (rows as any[]).map(rowToTraceSummary);
-}
-
-export async function getTraceSummary(
-  runId: string,
-  opts: { userId?: string } = {},
-): Promise<TraceSummary | null> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { where, args } = withUserFilter("run_id = ?", [runId], opts.userId);
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_trace_summaries WHERE ${where}`,
-    args,
-  });
-  if (rows.length === 0) return null;
-  return rowToTraceSummary(rows[0] as any);
-}
-
-// ─── Feedback CRUD ───────────────────────────────────────────────────
-
-export async function insertFeedback(entry: FeedbackEntry): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  await client.execute({
-    sql: `INSERT INTO agent_feedback
-      (id, run_id, thread_id, message_seq, feedback_type, value, user_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-    args: [
-      entry.id,
-      entry.runId,
-      entry.threadId,
-      entry.messageSeq,
-      entry.feedbackType,
-      entry.value,
-      entry.userId,
-      entry.createdAt,
-    ],
-  });
-}
-
-export async function getFeedback(opts: {
-  threadId?: string;
-  sinceMs?: number;
-  limit?: number;
-  feedbackType?: string;
-  userId?: string;
-}): Promise<FeedbackEntry[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const conditions: string[] = [];
-  const args: any[] = [];
-  if (opts.threadId) {
-    conditions.push("thread_id = ?");
-    args.push(opts.threadId);
-  }
-  if (opts.sinceMs) {
-    conditions.push("created_at >= ?");
-    args.push(opts.sinceMs);
-  }
-  if (opts.feedbackType) {
-    conditions.push("feedback_type = ?");
-    args.push(opts.feedbackType);
-  }
-  if (opts.userId) {
-    conditions.push("user_id = ?");
-    args.push(opts.userId);
-  }
-  const where =
-    conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-  const limit = opts.limit ?? 100;
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_feedback ${where} ORDER BY created_at DESC LIMIT ?`,
-    args: [...args, limit],
-  });
-  return (rows as any[]).map(rowToFeedback);
-}
-
-export async function getFeedbackStats(
-  sinceMs: number,
-  opts: { userId?: string } = {},
-): Promise<{
-  total: number;
-  thumbsUp: number;
-  thumbsDown: number;
-  categories: Record<string, number>;
-}> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { where, args } = withUserFilter(
-    "created_at >= ?",
-    [sinceMs],
-    opts.userId,
-  );
-  const { rows } = await client.execute({
-    sql: `SELECT feedback_type, value, COUNT(*) as cnt
-      FROM agent_feedback WHERE ${where}
-      GROUP BY feedback_type, value`,
-    args,
-  });
-  let total = 0;
-  let thumbsUp = 0;
-  let thumbsDown = 0;
-  const categories: Record<string, number> = {};
-  for (const row of rows as any[]) {
-    const cnt = Number(row.cnt);
-    total += cnt;
-    if (row.feedback_type === "thumbs_up") thumbsUp += cnt;
-    else if (row.feedback_type === "thumbs_down") thumbsDown += cnt;
-    else if (row.feedback_type === "category")
-      categories[String(row.value)] = cnt;
-  }
-  return { total, thumbsUp, thumbsDown, categories };
-}
-
-// ─── Satisfaction scores CRUD ────────────────────────────────────────
-
-export async function upsertSatisfactionScore(
-  score: SatisfactionScore,
-): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  if (isPostgres()) {
-    await client.execute({
-      sql: `INSERT INTO agent_satisfaction_scores
-        (id, thread_id, user_id, frustration_score, rephrasing_score,
-         abandonment_score, sentiment_score, length_trend_score, computed_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT (id) DO UPDATE SET
-          frustration_score = EXCLUDED.frustration_score,
-          rephrasing_score = EXCLUDED.rephrasing_score,
-          abandonment_score = EXCLUDED.abandonment_score,
-          sentiment_score = EXCLUDED.sentiment_score,
-          length_trend_score = EXCLUDED.length_trend_score,
-          computed_at = EXCLUDED.computed_at`,
-      args: [
-        score.id,
-        score.threadId,
-        score.userId,
-        score.frustrationScore,
-        score.rephrasingScore,
-        score.abandonmentScore,
-        score.sentimentScore,
-        score.lengthTrendScore,
-        score.computedAt,
-      ],
-    });
-  } else {
-    await client.execute({
-      sql: `INSERT INTO agent_satisfaction_scores
-        (id, thread_id, user_id, frustration_score, rephrasing_score,
-         abandonment_score, sentiment_score, length_trend_score, computed_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT (id) DO UPDATE SET
-          frustration_score = EXCLUDED.frustration_score,
-          rephrasing_score = EXCLUDED.rephrasing_score,
-          abandonment_score = EXCLUDED.abandonment_score,
-          sentiment_score = EXCLUDED.sentiment_score,
-          length_trend_score = EXCLUDED.length_trend_score,
-          computed_at = EXCLUDED.computed_at`,
-      args: [
-        score.id,
-        score.threadId,
-        score.userId,
-        score.frustrationScore,
-        score.rephrasingScore,
-        score.abandonmentScore,
-        score.sentimentScore,
-        score.lengthTrendScore,
-        score.computedAt,
-      ],
-    });
-  }
-}
-
-export async function getSatisfactionScores(opts: {
-  sinceMs?: number;
-  limit?: number;
-  minFrustration?: number;
-  userId?: string;
-}): Promise<SatisfactionScore[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const conditions: string[] = [];
-  const args: any[] = [];
-  if (opts.sinceMs) {
-    conditions.push("computed_at >= ?");
-    args.push(opts.sinceMs);
-  }
-  if (opts.minFrustration != null) {
-    conditions.push("frustration_score >= ?");
-    args.push(opts.minFrustration);
-  }
-  if (opts.userId) {
-    conditions.push("user_id = ?");
-    args.push(opts.userId);
-  }
-  const where =
-    conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_satisfaction_scores ${where}
-      ORDER BY computed_at DESC LIMIT ?`,
-    args: [...args, opts.limit ?? 100],
-  });
-  return (rows as any[]).map(rowToSatisfaction);
-}
-
-// ─── Evals CRUD ──────────────────────────────────────────────────────
-
-export async function insertEvalResult(result: EvalResult): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  await client.execute({
-    sql: `INSERT INTO agent_evals
-      (id, run_id, thread_id, user_id, eval_type, criteria, score, reasoning, metadata, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    args: [
-      result.id,
-      result.runId,
-      result.threadId,
-      result.userId,
-      result.evalType,
-      result.criteria,
-      result.score,
-      result.reasoning,
-      result.metadata ? JSON.stringify(result.metadata) : null,
-      result.createdAt,
-    ],
-  });
-}
-
-export async function getEvalsForRun(
-  runId: string,
-  opts: { userId?: string } = {},
-): Promise<EvalResult[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { where, args } = withUserFilter("run_id = ?", [runId], opts.userId);
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_evals WHERE ${where} ORDER BY created_at ASC`,
-    args,
-  });
-  return (rows as any[]).map(rowToEval);
-}
-
-export async function getEvalStats(
-  sinceMs: number,
-  opts: { userId?: string } = {},
-): Promise<{
-  totalEvals: number;
-  avgScore: number;
-  byCriteria: Array<{ criteria: string; avgScore: number; count: number }>;
-}> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { where, args } = withUserFilter(
-    "created_at >= ?",
-    [sinceMs],
-    opts.userId,
-  );
-  const { rows: totalRows } = await client.execute({
-    sql: `SELECT COUNT(*) as cnt, AVG(score) as avg_score
-      FROM agent_evals WHERE ${where}`,
-    args,
-  });
-  const t = (totalRows[0] ?? {}) as Record<string, number | null>;
-
-  const { rows: criteriaRows } = await client.execute({
-    sql: `SELECT criteria, AVG(score) as avg_score, COUNT(*) as cnt
-      FROM agent_evals WHERE ${where}
-      GROUP BY criteria ORDER BY cnt DESC`,
-    args,
-  });
-
-  return {
-    totalEvals: Number(t.cnt ?? 0),
-    avgScore: Number(t.avg_score ?? 0),
-    byCriteria: (criteriaRows as any[]).map((r) => ({
-      criteria: String(r.criteria),
-      avgScore: Number(r.avg_score ?? 0),
-      count: Number(r.cnt ?? 0),
-    })),
-  };
-}
-
-// ─── Eval datasets CRUD ──────────────────────────────────────────────
-
-export async function insertEvalDataset(dataset: EvalDataset): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  await client.execute({
-    sql: `INSERT INTO agent_eval_datasets
-      (id, name, description, entries, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?)`,
-    args: [
-      dataset.id,
-      dataset.name,
-      dataset.description,
-      JSON.stringify(dataset.entries),
-      dataset.createdAt,
-      dataset.updatedAt,
-    ],
-  });
-}
-
-export async function listEvalDatasets(): Promise<EvalDataset[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { rows } = await client.execute(
-    `SELECT * FROM agent_eval_datasets ORDER BY updated_at DESC`,
-  );
-  return (rows as any[]).map(rowToDataset);
-}
-
-export async function getEvalDataset(id: string): Promise<EvalDataset | null> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_eval_datasets WHERE id = ?`,
-    args: [id],
-  });
-  if (rows.length === 0) return null;
-  return rowToDataset(rows[0] as any);
-}
-
-export async function updateEvalDataset(
-  id: string,
-  updates: Partial<Pick<EvalDataset, "name" | "description" | "entries">>,
-): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const sets: string[] = [];
-  const args: any[] = [];
-  if (updates.name !== undefined) {
-    sets.push("name = ?");
-    args.push(updates.name);
-  }
-  if (updates.description !== undefined) {
-    sets.push("description = ?");
-    args.push(updates.description);
-  }
-  if (updates.entries !== undefined) {
-    sets.push("entries = ?");
-    args.push(JSON.stringify(updates.entries));
-  }
-  sets.push("updated_at = ?");
-  args.push(Date.now());
-  args.push(id);
-  await client.execute({
-    sql: `UPDATE agent_eval_datasets SET ${sets.join(", ")} WHERE id = ?`,
-    args,
-  });
-}
-
-// ─── Experiments CRUD ────────────────────────────────────────────────
-
-export async function insertExperiment(exp: Experiment): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  await client.execute({
-    sql: `INSERT INTO agent_experiments
-      (id, name, status, variants, metrics, assignment_level,
-       started_at, ended_at, created_at, owner_email)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    args: [
-      exp.id,
-      exp.name,
-      exp.status,
-      JSON.stringify(exp.variants),
-      JSON.stringify(exp.metrics),
-      exp.assignmentLevel,
-      exp.startedAt,
-      exp.endedAt,
-      exp.createdAt,
-      exp.ownerEmail ?? null,
-    ],
-  });
-}
-
-export async function updateExperiment(
-  id: string,
-  updates: Partial<
-    Pick<Experiment, "name" | "status" | "variants" | "metrics" | "endedAt">
-  >,
-): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const sets: string[] = [];
-  const args: any[] = [];
-  if (updates.name !== undefined) {
-    sets.push("name = ?");
-    args.push(updates.name);
-  }
-  if (updates.status !== undefined) {
-    sets.push("status = ?");
-    args.push(updates.status);
-    if (updates.status === "running" && !updates.endedAt) {
-      sets.push("started_at = ?");
-      args.push(Date.now());
-    }
-  }
-  if (updates.variants !== undefined) {
-    sets.push("variants = ?");
-    args.push(JSON.stringify(updates.variants));
-  }
-  if (updates.metrics !== undefined) {
-    sets.push("metrics = ?");
-    args.push(JSON.stringify(updates.metrics));
-  }
-  if (updates.endedAt !== undefined) {
-    sets.push("ended_at = ?");
-    args.push(updates.endedAt);
-  }
-  if (sets.length === 0) return;
-  args.push(id);
-  await client.execute({
-    sql: `UPDATE agent_experiments SET ${sets.join(", ")} WHERE id = ?`,
-    args,
-  });
-}
-
-export async function listExperiments(): Promise<Experiment[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { rows } = await client.execute(
-    `SELECT * FROM agent_experiments ORDER BY created_at DESC`,
-  );
-  return (rows as any[]).map(rowToExperiment);
-}
-
-export async function getExperiment(id: string): Promise<Experiment | null> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_experiments WHERE id = ?`,
-    args: [id],
-  });
-  if (rows.length === 0) return null;
-  return rowToExperiment(rows[0] as any);
-}
-
-// ─── Experiment assignments CRUD ────────────────────────────────────
-
-export async function upsertAssignment(
-  assignment: ExperimentAssignment,
-): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  if (isPostgres()) {
-    await client.execute({
-      sql: `INSERT INTO agent_experiment_assignments
-        (experiment_id, user_id, variant_id, assigned_at)
-        VALUES (?, ?, ?, ?)
-        ON CONFLICT (experiment_id, user_id) DO UPDATE SET
-          variant_id = EXCLUDED.variant_id,
-          assigned_at = EXCLUDED.assigned_at`,
-      args: [
-        assignment.experimentId,
-        assignment.userId,
-        assignment.variantId,
-        assignment.assignedAt,
-      ],
-    });
-  } else {
-    await client.execute({
-      sql: `INSERT OR REPLACE INTO agent_experiment_assignments
-        (experiment_id, user_id, variant_id, assigned_at)
-        VALUES (?, ?, ?, ?)`,
-      args: [
-        assignment.experimentId,
-        assignment.userId,
-        assignment.variantId,
-        assignment.assignedAt,
-      ],
-    });
-  }
-}
-
-export async function getAssignment(
-  experimentId: string,
-  userId: string,
-): Promise<ExperimentAssignment | null> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_experiment_assignments
-      WHERE experiment_id = ? AND user_id = ?`,
-    args: [experimentId, userId],
-  });
-  if (rows.length === 0) return null;
-  const r = rows[0] as any;
-  return {
-    experimentId: r.experiment_id,
-    userId: r.user_id,
-    variantId: r.variant_id,
-    assignedAt: Number(r.assigned_at),
-  };
-}
-
-// ─── Experiment results CRUD ─────────────────────────────────────────
-
-export async function insertExperimentResult(
-  result: ExperimentMetricResult,
-): Promise<void> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  await client.execute({
-    sql: `INSERT INTO agent_experiment_results
-      (id, experiment_id, variant_id, metric, value,
-       sample_size, confidence_low, confidence_high, computed_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    args: [
-      result.id,
-      result.experimentId,
-      result.variantId,
-      result.metric,
-      result.value,
-      result.sampleSize,
-      result.confidenceLow,
-      result.confidenceHigh,
-      result.computedAt,
-    ],
-  });
-}
-
-export async function getExperimentResults(
-  experimentId: string,
-): Promise<ExperimentMetricResult[]> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-  const { rows } = await client.execute({
-    sql: `SELECT * FROM agent_experiment_results
-      WHERE experiment_id = ?
-      ORDER BY computed_at DESC`,
-    args: [experimentId],
-  });
-  return (rows as any[]).map(rowToExperimentResult);
-}
-
-// ─── Aggregate queries for dashboard ─────────────────────────────────
-
-export async function getObservabilityOverview(
-  sinceMs: number,
-  opts: { userId?: string } = {},
-): Promise<{
-  totalRuns: number;
-  totalCostCents: number;
-  avgDurationMs: number;
-  toolSuccessRate: number;
-  avgFrustrationScore: number;
-  thumbsUpRate: number;
-  avgEvalScore: number;
-}> {
-  await ensureObservabilityTables();
-  const client = getDbExec();
-
-  // Three of the four sub-queries time-key on `created_at`; satisfaction
-  // uses `computed_at`. Each gets its own `withUserFilter` invocation so
-  // the args array isn't aliased across calls (some drivers mutate args
-  // for prepared-statement caching).
-  const created = withUserFilter("created_at >= ?", [sinceMs], opts.userId);
-  const computed = withUserFilter("computed_at >= ?", [sinceMs], opts.userId);
-
-  const [tracesResult, satisfactionResult, feedbackResult, evalsResult] =
-    await Promise.all([
-      client.execute({
-        sql: `SELECT
-          COUNT(*) as total_runs,
-          COALESCE(SUM(total_cost_cents_x100), 0) as total_cost,
-          COALESCE(AVG(total_duration_ms), 0) as avg_duration,
-          COALESCE(SUM(successful_tools), 0) as success_tools,
-          COALESCE(SUM(tool_calls), 0) as total_tools
-          FROM agent_trace_summaries WHERE ${created.where}`,
-        args: created.args,
-      }),
-      client.execute({
-        sql: `SELECT COALESCE(AVG(frustration_score), 0) as avg_frustration
-          FROM agent_satisfaction_scores WHERE ${computed.where}`,
-        args: computed.args,
-      }),
-      client.execute({
-        sql: `SELECT
-          COALESCE(SUM(CASE WHEN feedback_type = 'thumbs_up' THEN 1 ELSE 0 END), 0) as up,
-          COALESCE(SUM(CASE WHEN feedback_type IN ('thumbs_up', 'thumbs_down') THEN 1 ELSE 0 END), 0) as total
-          FROM agent_feedback WHERE ${created.where}`,
-        args: created.args,
-      }),
-      client.execute({
-        sql: `SELECT COALESCE(AVG(score), 0) as avg_score
-          FROM agent_evals WHERE ${created.where}`,
-        args: created.args,
-      }),
-    ]);
-
-  const t = (tracesResult.rows[0] ?? {}) as Record<string, number | null>;
-  const s = (satisfactionResult.rows[0] ?? {}) as Record<string, number | null>;
-  const f = (feedbackResult.rows[0] ?? {}) as Record<string, number | null>;
-  const e = (evalsResult.rows[0] ?? {}) as Record<string, number | null>;
-
-  const totalTools = Number(t.total_tools ?? 0);
-  const successTools = Number(t.success_tools ?? 0);
-  const feedbackTotal = Number(f.total ?? 0);
-  const feedbackUp = Number(f.up ?? 0);
-
-  return {
-    totalRuns: Number(t.total_runs ?? 0),
-    totalCostCents: Number(t.total_cost ?? 0) / 100,
-    avgDurationMs: Number(t.avg_duration ?? 0),
-    toolSuccessRate: totalTools > 0 ? successTools / totalTools : 1,
-    avgFrustrationScore: Number(s.avg_frustration ?? 0),
-    thumbsUpRate: feedbackTotal > 0 ? feedbackUp / feedbackTotal : 0,
-    avgEvalScore: Number(e.avg_score ?? 0),
-  };
-}
-
-// ─── Row mappers ─────────────────────────────────────────────────────
-
-function rowToTraceSpan(row: Record<string, any>): TraceSpan {
-  return {
-    id: String(row.id),
-    runId: String(row.run_id),
-    threadId: row.thread_id ? String(row.thread_id) : null,
-    userId: row.user_id ? String(row.user_id) : null,
-    parentSpanId: row.parent_span_id ? String(row.parent_span_id) : null,
-    spanType: row.span_type as TraceSpan["spanType"],
-    name: String(row.name),
-    inputTokens: Number(row.input_tokens ?? 0),
-    outputTokens: Number(row.output_tokens ?? 0),
-    cacheReadTokens: Number(row.cache_read_tokens ?? 0),
-    cacheWriteTokens: Number(row.cache_write_tokens ?? 0),
-    costCentsX100: Number(row.cost_cents_x100 ?? 0),
-    durationMs: Number(row.duration_ms ?? 0),
-    status: row.status as TraceSpan["status"],
-    errorMessage: row.error_message ? String(row.error_message) : null,
-    metadata: safeJsonParse(row.metadata, null),
-    createdAt: Number(row.created_at),
-  };
-}
-
-function rowToTraceSummary(row: Record<string, any>): TraceSummary {
-  return {
-    runId: String(row.run_id),
-    threadId: row.thread_id ? String(row.thread_id) : null,
-    userId: row.user_id ? String(row.user_id) : null,
-    totalSpans: Number(row.total_spans ?? 0),
-    llmCalls: Number(row.llm_calls ?? 0),
-    toolCalls: Number(row.tool_calls ?? 0),
-    successfulTools: Number(row.successful_tools ?? 0),
-    failedTools: Number(row.failed_tools ?? 0),
-    totalDurationMs: Number(row.total_duration_ms ?? 0),
-    totalCostCentsX100: Number(row.total_cost_cents_x100 ?? 0),
-    totalInputTokens: Number(row.total_input_tokens ?? 0),
-    totalOutputTokens: Number(row.total_output_tokens ?? 0),
-    model: String(row.model ?? ""),
-    createdAt: Number(row.created_at),
-  };
-}
-
-function rowToFeedback(row: Record<string, any>): FeedbackEntry {
-  return {
-    id: String(row.id),
-    runId: row.run_id ? String(row.run_id) : null,
-    threadId: row.thread_id ? String(row.thread_id) : null,
-    messageSeq: row.message_seq != null ? Number(row.message_seq) : null,
-    feedbackType: row.feedback_type as FeedbackEntry["feedbackType"],
-    value: String(row.value ?? ""),
-    userId: row.user_id ? String(row.user_id) : null,
-    createdAt: Number(row.created_at),
-  };
-}
-
-function rowToSatisfaction(row: Record<string, any>): SatisfactionScore {
-  return {
-    id: String(row.id),
-    threadId: String(row.thread_id),
-    userId: row.user_id ? String(row.user_id) : null,
-    frustrationScore: Number(row.frustration_score ?? 0),
-    rephrasingScore: Number(row.rephrasing_score ?? 0),
-    abandonmentScore: Number(row.abandonment_score ?? 0),
-    sentimentScore: Number(row.sentiment_score ?? 0),
-    lengthTrendScore: Number(row.length_trend_score ?? 0),
-    computedAt: Number(row.computed_at),
-  };
-}
-
-function rowToEval(row: Record<string, any>): EvalResult {
-  return {
-    id: String(row.id),
-    runId: String(row.run_id),
-    threadId: row.thread_id ? String(row.thread_id) : null,
-    userId: row.user_id ? String(row.user_id) : null,
-    evalType: row.eval_type as EvalResult["evalType"],
-    criteria: String(row.criteria),
-    score: Number(row.score ?? 0),
-    reasoning: row.reasoning ? String(row.reasoning) : null,
-    metadata: safeJsonParse(row.metadata, null),
-    createdAt: Number(row.created_at),
-  };
-}
-
-function rowToDataset(row: Record<string, any>): EvalDataset {
-  return {
-    id: String(row.id),
-    name: String(row.name),
-    description: String(row.description ?? ""),
-    entries: safeJsonParse(row.entries, []),
-    createdAt: Number(row.created_at),
-    updatedAt: Number(row.updated_at),
-  };
-}
-
-function rowToExperiment(row: Record<string, any>): Experiment {
-  return {
-    id: String(row.id),
-    name: String(row.name),
-    status: row.status as Experiment["status"],
-    variants: safeJsonParse(row.variants, []),
-    metrics: safeJsonParse(row.metrics, []),
-    assignmentLevel: (row.assignment_level as "user" | "session") ?? "user",
-    startedAt: row.started_at ? Number(row.started_at) : null,
-    endedAt: row.ended_at ? Number(row.ended_at) : null,
-    createdAt: Number(row.created_at),
-    ownerEmail:
-      typeof row.owner_email === "string" && row.owner_email
-        ? row.owner_email
-        : null,
-  };
-}
-
-function rowToExperimentResult(
-  row: Record<string, any>,
-): ExperimentMetricResult {
-  return {
-    id: String(row.id),
-    experimentId: String(row.experiment_id),
-    variantId: String(row.variant_id),
-    metric: String(row.metric),
-    value: Number(row.value ?? 0),
-    sampleSize: Number(row.sample_size ?? 0),
-    confidenceLow: Number(row.confidence_low ?? 0),
-    confidenceHigh: Number(row.confidence_high ?? 0),
-    computedAt: Number(row.computed_at),
-  };
-}
+/**
+ * SQL persistence for the agent observability system.
+ *
+ * Creates and manages tables for traces, feedback, evals, experiments,
+ * and satisfaction scores. Follows the same raw-SQL pattern as
+ * run-store.ts and usage/store.ts — framework tables use getDbExec()
+ * rather than Drizzle ORM (which is for template-level schemas).
+ */
+import {
+  getDbExec,
+  intType,
+  isPostgres,
+  retryOnDdlRace,
+} from "../db/client.js";
+import {
+  ensureTableExists,
+  ensureColumnExists,
+  ensureIndexExists,
+} from "../db/ddl-guard.js";
+import { isDuplicateColumnError } from "../db/migrations.js";
+import { createInitMemo } from "../shared/init-memo.js";
+import type {
+  TraceSpan,
+  TraceSummary,
+  FeedbackEntry,
+  SatisfactionScore,
+  EvalResult,
+  EvalDataset,
+  Experiment,
+  ExperimentAssignment,
+  ExperimentMetricResult,
+} from "./types.js";
+
+function safeJsonParse<T>(value: unknown, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(String(value));
+  } catch {
+    return fallback;
+  }
+}
+
+// Tables whose rows are owned by an end user — drives the boot-time
+// user_id ALTER loop and the per-user composite indexes below. Every
+// new user-owned observability table must be added here so the upgrade
+// path and the per-user query plan stay in sync.
+const USER_SCOPED_TABLES = [
+  "agent_trace_spans",
+  "agent_trace_summaries",
+  "agent_satisfaction_scores",
+  "agent_evals",
+  "agent_feedback",
+] as const;
+
+/**
+ * Append an `AND user_id = ?` clause when a userId filter is requested.
+ * Returns the fully-bound WHERE clause + args ready to splice into the
+ * caller's SQL. Centralizes the pattern so tests can assert one shape.
+ */
+function withUserFilter(
+  baseWhere: string,
+  baseArgs: any[],
+  userId: string | undefined,
+): { where: string; args: any[] } {
+  if (userId == null) return { where: baseWhere, args: baseArgs };
+  return {
+    where: `${baseWhere} AND user_id = ?`,
+    args: [...baseArgs, userId],
+  };
+}
+
+// workerd-safe memo: the raw `let _initPromise` pattern wedged every agent
+// chat run on the unified Cloudflare runtime when an early-responding first
+// request created (and froze) the init promise — see shared/init-memo.ts.
+export const ensureObservabilityTables = createInitMemo(
+  async () => {
+    const client = getDbExec();
+
+    const traceSpansCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_trace_spans (
+          id TEXT PRIMARY KEY,
+          run_id TEXT NOT NULL,
+          thread_id TEXT,
+          user_id TEXT,
+          parent_span_id TEXT,
+          span_type TEXT NOT NULL,
+          name TEXT NOT NULL,
+          input_tokens ${intType()} NOT NULL DEFAULT 0,
+          output_tokens ${intType()} NOT NULL DEFAULT 0,
+          cache_read_tokens ${intType()} NOT NULL DEFAULT 0,
+          cache_write_tokens ${intType()} NOT NULL DEFAULT 0,
+          cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,
+          duration_ms ${intType()} NOT NULL DEFAULT 0,
+          status TEXT NOT NULL DEFAULT 'success',
+          error_message TEXT,
+          metadata TEXT,
+          created_at ${intType()} NOT NULL
+        )
+      `;
+
+    const traceSummariesCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_trace_summaries (
+          run_id TEXT PRIMARY KEY,
+          thread_id TEXT,
+          user_id TEXT,
+          total_spans ${intType()} NOT NULL DEFAULT 0,
+          llm_calls ${intType()} NOT NULL DEFAULT 0,
+          tool_calls ${intType()} NOT NULL DEFAULT 0,
+          successful_tools ${intType()} NOT NULL DEFAULT 0,
+          failed_tools ${intType()} NOT NULL DEFAULT 0,
+          total_duration_ms ${intType()} NOT NULL DEFAULT 0,
+          total_cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,
+          total_input_tokens ${intType()} NOT NULL DEFAULT 0,
+          total_output_tokens ${intType()} NOT NULL DEFAULT 0,
+          model TEXT NOT NULL DEFAULT '',
+          created_at ${intType()} NOT NULL
+        )
+      `;
+
+    const feedbackCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_feedback (
+          id TEXT PRIMARY KEY,
+          run_id TEXT,
+          thread_id TEXT,
+          message_seq ${intType()},
+          feedback_type TEXT NOT NULL,
+          value TEXT NOT NULL DEFAULT '',
+          user_id TEXT,
+          created_at ${intType()} NOT NULL
+        )
+      `;
+
+    const satisfactionScoresCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_satisfaction_scores (
+          id TEXT PRIMARY KEY,
+          thread_id TEXT NOT NULL,
+          user_id TEXT,
+          frustration_score REAL NOT NULL DEFAULT 0,
+          rephrasing_score REAL NOT NULL DEFAULT 0,
+          abandonment_score REAL NOT NULL DEFAULT 0,
+          sentiment_score REAL NOT NULL DEFAULT 0,
+          length_trend_score REAL NOT NULL DEFAULT 0,
+          computed_at ${intType()} NOT NULL
+        )
+      `;
+
+    const evalsCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_evals (
+          id TEXT PRIMARY KEY,
+          run_id TEXT NOT NULL,
+          thread_id TEXT,
+          user_id TEXT,
+          eval_type TEXT NOT NULL,
+          criteria TEXT NOT NULL,
+          score REAL NOT NULL DEFAULT 0,
+          reasoning TEXT,
+          metadata TEXT,
+          created_at ${intType()} NOT NULL
+        )
+      `;
+
+    const evalDatasetsCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_eval_datasets (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          description TEXT NOT NULL DEFAULT '',
+          entries TEXT NOT NULL DEFAULT '[]',
+          created_at ${intType()} NOT NULL,
+          updated_at ${intType()} NOT NULL
+        )
+      `;
+
+    const experimentsCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_experiments (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'draft',
+          variants TEXT NOT NULL DEFAULT '[]',
+          metrics TEXT NOT NULL DEFAULT '[]',
+          assignment_level TEXT NOT NULL DEFAULT 'user',
+          started_at ${intType()},
+          ended_at ${intType()},
+          created_at ${intType()} NOT NULL,
+          owner_email TEXT
+        )
+      `;
+
+    const experimentAssignmentsCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_experiment_assignments (
+          experiment_id TEXT NOT NULL,
+          user_id TEXT NOT NULL,
+          variant_id TEXT NOT NULL,
+          assigned_at ${intType()} NOT NULL,
+          PRIMARY KEY (experiment_id, user_id)
+        )
+      `;
+
+    const experimentResultsCreateSql = `
+        CREATE TABLE IF NOT EXISTS agent_experiment_results (
+          id TEXT PRIMARY KEY,
+          experiment_id TEXT NOT NULL,
+          variant_id TEXT NOT NULL,
+          metric TEXT NOT NULL,
+          value REAL NOT NULL DEFAULT 0,
+          sample_size ${intType()} NOT NULL DEFAULT 0,
+          confidence_low REAL NOT NULL DEFAULT 0,
+          confidence_high REAL NOT NULL DEFAULT 0,
+          computed_at ${intType()} NOT NULL
+        )
+      `;
+
+    if (isPostgres()) {
+      // PG guard: probe → guarded DDL → re-probe; skips lock on already-migrated path
+      await ensureTableExists("agent_trace_spans", traceSpansCreateSql);
+      await ensureTableExists("agent_trace_summaries", traceSummariesCreateSql);
+      await ensureTableExists("agent_feedback", feedbackCreateSql);
+      await ensureTableExists(
+        "agent_satisfaction_scores",
+        satisfactionScoresCreateSql,
+      );
+      await ensureTableExists("agent_evals", evalsCreateSql);
+      await ensureTableExists("agent_eval_datasets", evalDatasetsCreateSql);
+      await ensureTableExists("agent_experiments", experimentsCreateSql);
+      await ensureTableExists(
+        "agent_experiment_assignments",
+        experimentAssignmentsCreateSql,
+      );
+      await ensureTableExists(
+        "agent_experiment_results",
+        experimentResultsCreateSql,
+      );
+      await ensureColumnExists(
+        "agent_experiments",
+        "owner_email",
+        `ALTER TABLE agent_experiments ADD COLUMN IF NOT EXISTS owner_email TEXT`,
+      );
+      for (const table of USER_SCOPED_TABLES) {
+        await ensureColumnExists(
+          table,
+          "user_id",
+          `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS user_id TEXT`,
+        );
+      }
+      await ensureIndexExists(
+        "idx_trace_spans_run",
+        `CREATE INDEX IF NOT EXISTS idx_trace_spans_run ON agent_trace_spans (run_id)`,
+      );
+      await ensureIndexExists(
+        "idx_trace_spans_thread",
+        `CREATE INDEX IF NOT EXISTS idx_trace_spans_thread ON agent_trace_spans (thread_id)`,
+      );
+      await ensureIndexExists(
+        "idx_trace_spans_created",
+        `CREATE INDEX IF NOT EXISTS idx_trace_spans_created ON agent_trace_spans (created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_trace_summaries_created",
+        `CREATE INDEX IF NOT EXISTS idx_trace_summaries_created ON agent_trace_summaries (created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_trace_summaries_user",
+        `CREATE INDEX IF NOT EXISTS idx_trace_summaries_user ON agent_trace_summaries (user_id, created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_trace_spans_user",
+        `CREATE INDEX IF NOT EXISTS idx_trace_spans_user ON agent_trace_spans (user_id)`,
+      );
+      await ensureIndexExists(
+        "idx_feedback_thread",
+        `CREATE INDEX IF NOT EXISTS idx_feedback_thread ON agent_feedback (thread_id)`,
+      );
+      await ensureIndexExists(
+        "idx_feedback_created",
+        `CREATE INDEX IF NOT EXISTS idx_feedback_created ON agent_feedback (created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_feedback_user",
+        `CREATE INDEX IF NOT EXISTS idx_feedback_user ON agent_feedback (user_id, created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_satisfaction_thread",
+        `CREATE INDEX IF NOT EXISTS idx_satisfaction_thread ON agent_satisfaction_scores (thread_id)`,
+      );
+      await ensureIndexExists(
+        "idx_satisfaction_user",
+        `CREATE INDEX IF NOT EXISTS idx_satisfaction_user ON agent_satisfaction_scores (user_id, computed_at)`,
+      );
+      await ensureIndexExists(
+        "idx_evals_run",
+        `CREATE INDEX IF NOT EXISTS idx_evals_run ON agent_evals (run_id)`,
+      );
+      await ensureIndexExists(
+        "idx_evals_created",
+        `CREATE INDEX IF NOT EXISTS idx_evals_created ON agent_evals (created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_evals_user",
+        `CREATE INDEX IF NOT EXISTS idx_evals_user ON agent_evals (user_id, created_at)`,
+      );
+      await ensureIndexExists(
+        "idx_experiment_results_exp",
+        `CREATE INDEX IF NOT EXISTS idx_experiment_results_exp ON agent_experiment_results (experiment_id)`,
+      );
+      return;
+    }
+
+    // SQLite (local dev): no lock problem — keep the original behaviour.
+    await retryOnDdlRace(() => client.execute(traceSpansCreateSql));
+
+    await retryOnDdlRace(() => client.execute(traceSummariesCreateSql));
+
+    await retryOnDdlRace(() => client.execute(feedbackCreateSql));
+
+    await retryOnDdlRace(() => client.execute(satisfactionScoresCreateSql));
+
+    await retryOnDdlRace(() => client.execute(evalsCreateSql));
+
+    await retryOnDdlRace(() => client.execute(evalDatasetsCreateSql));
+
+    await retryOnDdlRace(() => client.execute(experimentsCreateSql));
+
+    // Additive migration for DBs created before the owner column shipped
+    // (any pre-existing rows have NULL owner — see `updateExperiment` for
+    // the migration semantics). Mutations on those rows fall back to the
+    // standard authentication gate but cannot enforce per-owner scoping
+    // until they're re-saved.
+    try {
+      await client.execute(
+        `ALTER TABLE agent_experiments ADD COLUMN owner_email TEXT`,
+      );
+    } catch {
+      // Column already exists — expected after first run.
+    }
+
+    await retryOnDdlRace(() => client.execute(experimentAssignmentsCreateSql));
+
+    await retryOnDdlRace(() => client.execute(experimentResultsCreateSql));
+
+    // Idempotent column upgrades for DBs created before per-user
+    // isolation. SQLite has no `ADD COLUMN IF NOT EXISTS`; Postgres
+    // surfaces "column ... already exists". `isDuplicateColumnError`
+    // (from db/migrations.ts) recognizes both shapes.
+    for (const table of USER_SCOPED_TABLES) {
+      try {
+        await client.execute(`ALTER TABLE ${table} ADD COLUMN user_id TEXT`);
+      } catch (err) {
+        if (isDuplicateColumnError(err)) continue;
+        throw err;
+      }
+    }
+
+    // Indexes for common query patterns
+    const indexes = [
+      `CREATE INDEX IF NOT EXISTS idx_trace_spans_run ON agent_trace_spans (run_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_trace_spans_thread ON agent_trace_spans (thread_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_trace_spans_created ON agent_trace_spans (created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_trace_summaries_created ON agent_trace_summaries (created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_trace_summaries_user ON agent_trace_summaries (user_id, created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_trace_spans_user ON agent_trace_spans (user_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_feedback_thread ON agent_feedback (thread_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_feedback_created ON agent_feedback (created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_feedback_user ON agent_feedback (user_id, created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_satisfaction_thread ON agent_satisfaction_scores (thread_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_satisfaction_user ON agent_satisfaction_scores (user_id, computed_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_evals_run ON agent_evals (run_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_evals_created ON agent_evals (created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_evals_user ON agent_evals (user_id, created_at)`,
+      `CREATE INDEX IF NOT EXISTS idx_experiment_results_exp ON agent_experiment_results (experiment_id)`,
+    ];
+    for (const sql of indexes) {
+      try {
+        await client.execute(sql);
+      } catch {
+        // Index might already exist
+      }
+    }
+  },
+  { label: "observability" },
+);
+
+// ─── Trace span CRUD ─────────────────────────────────────────────────
+
+export async function insertTraceSpan(span: TraceSpan): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_trace_spans
+      (id, run_id, thread_id, user_id, parent_span_id, span_type, name,
+       input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+       cost_cents_x100, duration_ms, status, error_message, metadata, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      span.id,
+      span.runId,
+      span.threadId,
+      span.userId,
+      span.parentSpanId,
+      span.spanType,
+      span.name,
+      span.inputTokens,
+      span.outputTokens,
+      span.cacheReadTokens,
+      span.cacheWriteTokens,
+      span.costCentsX100,
+      span.durationMs,
+      span.status,
+      span.errorMessage,
+      span.metadata ? JSON.stringify(span.metadata) : null,
+      span.createdAt,
+    ],
+  });
+}
+
+export async function upsertTraceSummary(summary: TraceSummary): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  // user_id is intentionally NOT updated on conflict — once a run's
+  // owner is recorded it shouldn't change under us.
+  if (isPostgres()) {
+    await client.execute({
+      sql: `INSERT INTO agent_trace_summaries
+        (run_id, thread_id, user_id, total_spans, llm_calls, tool_calls,
+         successful_tools, failed_tools, total_duration_ms,
+         total_cost_cents_x100, total_input_tokens, total_output_tokens,
+         model, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (run_id) DO UPDATE SET
+          total_spans = EXCLUDED.total_spans,
+          llm_calls = EXCLUDED.llm_calls,
+          tool_calls = EXCLUDED.tool_calls,
+          successful_tools = EXCLUDED.successful_tools,
+          failed_tools = EXCLUDED.failed_tools,
+          total_duration_ms = EXCLUDED.total_duration_ms,
+          total_cost_cents_x100 = EXCLUDED.total_cost_cents_x100,
+          total_input_tokens = EXCLUDED.total_input_tokens,
+          total_output_tokens = EXCLUDED.total_output_tokens,
+          model = EXCLUDED.model`,
+      args: [
+        summary.runId,
+        summary.threadId,
+        summary.userId,
+        summary.totalSpans,
+        summary.llmCalls,
+        summary.toolCalls,
+        summary.successfulTools,
+        summary.failedTools,
+        summary.totalDurationMs,
+        summary.totalCostCentsX100,
+        summary.totalInputTokens,
+        summary.totalOutputTokens,
+        summary.model,
+        summary.createdAt,
+      ],
+    });
+  } else {
+    await client.execute({
+      sql: `INSERT INTO agent_trace_summaries
+        (run_id, thread_id, user_id, total_spans, llm_calls, tool_calls,
+         successful_tools, failed_tools, total_duration_ms,
+         total_cost_cents_x100, total_input_tokens, total_output_tokens,
+         model, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (run_id) DO UPDATE SET
+          total_spans = EXCLUDED.total_spans,
+          llm_calls = EXCLUDED.llm_calls,
+          tool_calls = EXCLUDED.tool_calls,
+          successful_tools = EXCLUDED.successful_tools,
+          failed_tools = EXCLUDED.failed_tools,
+          total_duration_ms = EXCLUDED.total_duration_ms,
+          total_cost_cents_x100 = EXCLUDED.total_cost_cents_x100,
+          total_input_tokens = EXCLUDED.total_input_tokens,
+          total_output_tokens = EXCLUDED.total_output_tokens,
+          model = EXCLUDED.model`,
+      args: [
+        summary.runId,
+        summary.threadId,
+        summary.userId,
+        summary.totalSpans,
+        summary.llmCalls,
+        summary.toolCalls,
+        summary.successfulTools,
+        summary.failedTools,
+        summary.totalDurationMs,
+        summary.totalCostCentsX100,
+        summary.totalInputTokens,
+        summary.totalOutputTokens,
+        summary.model,
+        summary.createdAt,
+      ],
+    });
+  }
+}
+
+/**
+ * Purge trace spans, summaries, and eval results older than `cutoffMs`
+ * (a Unix epoch in milliseconds — rows with `created_at < cutoffMs` are
+ * deleted). Returns the per-table deletion counts. Satisfies the span
+ * retention TTL noted in /tmp/security-audit/12-mcp-a2a-agent.md
+ * (MEDIUM #14): trace metadata can hold sensitive tool inputs, so we
+ * cap the storage horizon. Feedback rows are retained — they're
+ * intentionally durable for product analytics. Experiments and
+ * datasets are also retained because they are user-authored
+ * configuration, not call telemetry.
+ */
+export async function deleteOldTraceData(cutoffMs: number): Promise<{
+  spans: number;
+  summaries: number;
+  evals: number;
+}> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const cutoff = Math.floor(cutoffMs);
+
+  const [spansResult, summariesResult, evalsResult] = await Promise.all([
+    client.execute({
+      sql: `DELETE FROM agent_trace_spans WHERE created_at < ?`,
+      args: [cutoff],
+    }),
+    client.execute({
+      sql: `DELETE FROM agent_trace_summaries WHERE created_at < ?`,
+      args: [cutoff],
+    }),
+    client.execute({
+      sql: `DELETE FROM agent_evals WHERE created_at < ?`,
+      args: [cutoff],
+    }),
+  ]);
+
+  return {
+    spans: Number(spansResult.rowsAffected ?? 0),
+    summaries: Number(summariesResult.rowsAffected ?? 0),
+    evals: Number(evalsResult.rowsAffected ?? 0),
+  };
+}
+
+export async function getTraceSpansForRun(
+  runId: string,
+  opts: { userId?: string } = {},
+): Promise<TraceSpan[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { where, args } = withUserFilter("run_id = ?", [runId], opts.userId);
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_trace_spans WHERE ${where} ORDER BY created_at ASC`,
+    args,
+  });
+  return (rows as any[]).map(rowToTraceSpan);
+}
+
+export async function getTraceSummaries(opts: {
+  sinceMs?: number;
+  limit?: number;
+  userId?: string;
+}): Promise<TraceSummary[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const sinceMs = opts.sinceMs ?? 0;
+  const limit = opts.limit ?? 100;
+  const { where, args } = withUserFilter(
+    "created_at >= ?",
+    [sinceMs],
+    opts.userId,
+  );
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_trace_summaries
+      WHERE ${where}
+      ORDER BY created_at DESC
+      LIMIT ?`,
+    args: [...args, limit],
+  });
+  return (rows as any[]).map(rowToTraceSummary);
+}
+
+export async function getTraceSummary(
+  runId: string,
+  opts: { userId?: string } = {},
+): Promise<TraceSummary | null> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { where, args } = withUserFilter("run_id = ?", [runId], opts.userId);
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_trace_summaries WHERE ${where}`,
+    args,
+  });
+  if (rows.length === 0) return null;
+  return rowToTraceSummary(rows[0] as any);
+}
+
+// ─── Feedback CRUD ───────────────────────────────────────────────────
+
+export async function insertFeedback(entry: FeedbackEntry): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_feedback
+      (id, run_id, thread_id, message_seq, feedback_type, value, user_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      entry.id,
+      entry.runId,
+      entry.threadId,
+      entry.messageSeq,
+      entry.feedbackType,
+      entry.value,
+      entry.userId,
+      entry.createdAt,
+    ],
+  });
+}
+
+export async function getFeedback(opts: {
+  threadId?: string;
+  sinceMs?: number;
+  limit?: number;
+  feedbackType?: string;
+  userId?: string;
+}): Promise<FeedbackEntry[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const conditions: string[] = [];
+  const args: any[] = [];
+  if (opts.threadId) {
+    conditions.push("thread_id = ?");
+    args.push(opts.threadId);
+  }
+  if (opts.sinceMs) {
+    conditions.push("created_at >= ?");
+    args.push(opts.sinceMs);
+  }
+  if (opts.feedbackType) {
+    conditions.push("feedback_type = ?");
+    args.push(opts.feedbackType);
+  }
+  if (opts.userId) {
+    conditions.push("user_id = ?");
+    args.push(opts.userId);
+  }
+  const where =
+    conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = opts.limit ?? 100;
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_feedback ${where} ORDER BY created_at DESC LIMIT ?`,
+    args: [...args, limit],
+  });
+  return (rows as any[]).map(rowToFeedback);
+}
+
+export async function getFeedbackStats(
+  sinceMs: number,
+  opts: { userId?: string } = {},
+): Promise<{
+  total: number;
+  thumbsUp: number;
+  thumbsDown: number;
+  categories: Record<string, number>;
+}> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { where, args } = withUserFilter(
+    "created_at >= ?",
+    [sinceMs],
+    opts.userId,
+  );
+  const { rows } = await client.execute({
+    sql: `SELECT feedback_type, value, COUNT(*) as cnt
+      FROM agent_feedback WHERE ${where}
+      GROUP BY feedback_type, value`,
+    args,
+  });
+  let total = 0;
+  let thumbsUp = 0;
+  let thumbsDown = 0;
+  const categories: Record<string, number> = {};
+  for (const row of rows as any[]) {
+    const cnt = Number(row.cnt);
+    total += cnt;
+    if (row.feedback_type === "thumbs_up") thumbsUp += cnt;
+    else if (row.feedback_type === "thumbs_down") thumbsDown += cnt;
+    else if (row.feedback_type === "category")
+      categories[String(row.value)] = cnt;
+  }
+  return { total, thumbsUp, thumbsDown, categories };
+}
+
+// ─── Satisfaction scores CRUD ────────────────────────────────────────
+
+export async function upsertSatisfactionScore(
+  score: SatisfactionScore,
+): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  if (isPostgres()) {
+    await client.execute({
+      sql: `INSERT INTO agent_satisfaction_scores
+        (id, thread_id, user_id, frustration_score, rephrasing_score,
+         abandonment_score, sentiment_score, length_trend_score, computed_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (id) DO UPDATE SET
+          frustration_score = EXCLUDED.frustration_score,
+          rephrasing_score = EXCLUDED.rephrasing_score,
+          abandonment_score = EXCLUDED.abandonment_score,
+          sentiment_score = EXCLUDED.sentiment_score,
+          length_trend_score = EXCLUDED.length_trend_score,
+          computed_at = EXCLUDED.computed_at`,
+      args: [
+        score.id,
+        score.threadId,
+        score.userId,
+        score.frustrationScore,
+        score.rephrasingScore,
+        score.abandonmentScore,
+        score.sentimentScore,
+        score.lengthTrendScore,
+        score.computedAt,
+      ],
+    });
+  } else {
+    await client.execute({
+      sql: `INSERT INTO agent_satisfaction_scores
+        (id, thread_id, user_id, frustration_score, rephrasing_score,
+         abandonment_score, sentiment_score, length_trend_score, computed_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (id) DO UPDATE SET
+          frustration_score = EXCLUDED.frustration_score,
+          rephrasing_score = EXCLUDED.rephrasing_score,
+          abandonment_score = EXCLUDED.abandonment_score,
+          sentiment_score = EXCLUDED.sentiment_score,
+          length_trend_score = EXCLUDED.length_trend_score,
+          computed_at = EXCLUDED.computed_at`,
+      args: [
+        score.id,
+        score.threadId,
+        score.userId,
+        score.frustrationScore,
+        score.rephrasingScore,
+        score.abandonmentScore,
+        score.sentimentScore,
+        score.lengthTrendScore,
+        score.computedAt,
+      ],
+    });
+  }
+}
+
+export async function getSatisfactionScores(opts: {
+  sinceMs?: number;
+  limit?: number;
+  minFrustration?: number;
+  userId?: string;
+}): Promise<SatisfactionScore[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const conditions: string[] = [];
+  const args: any[] = [];
+  if (opts.sinceMs) {
+    conditions.push("computed_at >= ?");
+    args.push(opts.sinceMs);
+  }
+  if (opts.minFrustration != null) {
+    conditions.push("frustration_score >= ?");
+    args.push(opts.minFrustration);
+  }
+  if (opts.userId) {
+    conditions.push("user_id = ?");
+    args.push(opts.userId);
+  }
+  const where =
+    conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_satisfaction_scores ${where}
+      ORDER BY computed_at DESC LIMIT ?`,
+    args: [...args, opts.limit ?? 100],
+  });
+  return (rows as any[]).map(rowToSatisfaction);
+}
+
+// ─── Evals CRUD ──────────────────────────────────────────────────────
+
+export async function insertEvalResult(result: EvalResult): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_evals
+      (id, run_id, thread_id, user_id, eval_type, criteria, score, reasoning, metadata, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      result.id,
+      result.runId,
+      result.threadId,
+      result.userId,
+      result.evalType,
+      result.criteria,
+      result.score,
+      result.reasoning,
+      result.metadata ? JSON.stringify(result.metadata) : null,
+      result.createdAt,
+    ],
+  });
+}
+
+export async function getEvalsForRun(
+  runId: string,
+  opts: { userId?: string } = {},
+): Promise<EvalResult[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { where, args } = withUserFilter("run_id = ?", [runId], opts.userId);
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_evals WHERE ${where} ORDER BY created_at ASC`,
+    args,
+  });
+  return (rows as any[]).map(rowToEval);
+}
+
+export async function getEvalStats(
+  sinceMs: number,
+  opts: { userId?: string } = {},
+): Promise<{
+  totalEvals: number;
+  avgScore: number;
+  byCriteria: Array<{ criteria: string; avgScore: number; count: number }>;
+}> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { where, args } = withUserFilter(
+    "created_at >= ?",
+    [sinceMs],
+    opts.userId,
+  );
+  const { rows: totalRows } = await client.execute({
+    sql: `SELECT COUNT(*) as cnt, AVG(score) as avg_score
+      FROM agent_evals WHERE ${where}`,
+    args,
+  });
+  const t = (totalRows[0] ?? {}) as Record<string, number | null>;
+
+  const { rows: criteriaRows } = await client.execute({
+    sql: `SELECT criteria, AVG(score) as avg_score, COUNT(*) as cnt
+      FROM agent_evals WHERE ${where}
+      GROUP BY criteria ORDER BY cnt DESC`,
+    args,
+  });
+
+  return {
+    totalEvals: Number(t.cnt ?? 0),
+    avgScore: Number(t.avg_score ?? 0),
+    byCriteria: (criteriaRows as any[]).map((r) => ({
+      criteria: String(r.criteria),
+      avgScore: Number(r.avg_score ?? 0),
+      count: Number(r.cnt ?? 0),
+    })),
+  };
+}
+
+// ─── Eval datasets CRUD ──────────────────────────────────────────────
+
+export async function insertEvalDataset(dataset: EvalDataset): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_eval_datasets
+      (id, name, description, entries, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)`,
+    args: [
+      dataset.id,
+      dataset.name,
+      dataset.description,
+      JSON.stringify(dataset.entries),
+      dataset.createdAt,
+      dataset.updatedAt,
+    ],
+  });
+}
+
+export async function listEvalDatasets(): Promise<EvalDataset[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { rows } = await client.execute(
+    `SELECT * FROM agent_eval_datasets ORDER BY updated_at DESC`,
+  );
+  return (rows as any[]).map(rowToDataset);
+}
+
+export async function getEvalDataset(id: string): Promise<EvalDataset | null> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_eval_datasets WHERE id = ?`,
+    args: [id],
+  });
+  if (rows.length === 0) return null;
+  return rowToDataset(rows[0] as any);
+}
+
+export async function updateEvalDataset(
+  id: string,
+  updates: Partial<Pick<EvalDataset, "name" | "description" | "entries">>,
+): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const sets: string[] = [];
+  const args: any[] = [];
+  if (updates.name !== undefined) {
+    sets.push("name = ?");
+    args.push(updates.name);
+  }
+  if (updates.description !== undefined) {
+    sets.push("description = ?");
+    args.push(updates.description);
+  }
+  if (updates.entries !== undefined) {
+    sets.push("entries = ?");
+    args.push(JSON.stringify(updates.entries));
+  }
+  sets.push("updated_at = ?");
+  args.push(Date.now());
+  args.push(id);
+  await client.execute({
+    sql: `UPDATE agent_eval_datasets SET ${sets.join(", ")} WHERE id = ?`,
+    args,
+  });
+}
+
+// ─── Experiments CRUD ────────────────────────────────────────────────
+
+export async function insertExperiment(exp: Experiment): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_experiments
+      (id, name, status, variants, metrics, assignment_level,
+       started_at, ended_at, created_at, owner_email)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      exp.id,
+      exp.name,
+      exp.status,
+      JSON.stringify(exp.variants),
+      JSON.stringify(exp.metrics),
+      exp.assignmentLevel,
+      exp.startedAt,
+      exp.endedAt,
+      exp.createdAt,
+      exp.ownerEmail ?? null,
+    ],
+  });
+}
+
+export async function updateExperiment(
+  id: string,
+  updates: Partial<
+    Pick<Experiment, "name" | "status" | "variants" | "metrics" | "endedAt">
+  >,
+): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const sets: string[] = [];
+  const args: any[] = [];
+  if (updates.name !== undefined) {
+    sets.push("name = ?");
+    args.push(updates.name);
+  }
+  if (updates.status !== undefined) {
+    sets.push("status = ?");
+    args.push(updates.status);
+    if (updates.status === "running" && !updates.endedAt) {
+      sets.push("started_at = ?");
+      args.push(Date.now());
+    }
+  }
+  if (updates.variants !== undefined) {
+    sets.push("variants = ?");
+    args.push(JSON.stringify(updates.variants));
+  }
+  if (updates.metrics !== undefined) {
+    sets.push("metrics = ?");
+    args.push(JSON.stringify(updates.metrics));
+  }
+  if (updates.endedAt !== undefined) {
+    sets.push("ended_at = ?");
+    args.push(updates.endedAt);
+  }
+  if (sets.length === 0) return;
+  args.push(id);
+  await client.execute({
+    sql: `UPDATE agent_experiments SET ${sets.join(", ")} WHERE id = ?`,
+    args,
+  });
+}
+
+export async function listExperiments(): Promise<Experiment[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { rows } = await client.execute(
+    `SELECT * FROM agent_experiments ORDER BY created_at DESC`,
+  );
+  return (rows as any[]).map(rowToExperiment);
+}
+
+export async function getExperiment(id: string): Promise<Experiment | null> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_experiments WHERE id = ?`,
+    args: [id],
+  });
+  if (rows.length === 0) return null;
+  return rowToExperiment(rows[0] as any);
+}
+
+// ─── Experiment assignments CRUD ────────────────────────────────────
+
+export async function upsertAssignment(
+  assignment: ExperimentAssignment,
+): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  if (isPostgres()) {
+    await client.execute({
+      sql: `INSERT INTO agent_experiment_assignments
+        (experiment_id, user_id, variant_id, assigned_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (experiment_id, user_id) DO UPDATE SET
+          variant_id = EXCLUDED.variant_id,
+          assigned_at = EXCLUDED.assigned_at`,
+      args: [
+        assignment.experimentId,
+        assignment.userId,
+        assignment.variantId,
+        assignment.assignedAt,
+      ],
+    });
+  } else {
+    await client.execute({
+      sql: `INSERT OR REPLACE INTO agent_experiment_assignments
+        (experiment_id, user_id, variant_id, assigned_at)
+        VALUES (?, ?, ?, ?)`,
+      args: [
+        assignment.experimentId,
+        assignment.userId,
+        assignment.variantId,
+        assignment.assignedAt,
+      ],
+    });
+  }
+}
+
+export async function getAssignment(
+  experimentId: string,
+  userId: string,
+): Promise<ExperimentAssignment | null> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_experiment_assignments
+      WHERE experiment_id = ? AND user_id = ?`,
+    args: [experimentId, userId],
+  });
+  if (rows.length === 0) return null;
+  const r = rows[0] as any;
+  return {
+    experimentId: r.experiment_id,
+    userId: r.user_id,
+    variantId: r.variant_id,
+    assignedAt: Number(r.assigned_at),
+  };
+}
+
+// ─── Experiment results CRUD ─────────────────────────────────────────
+
+export async function insertExperimentResult(
+  result: ExperimentMetricResult,
+): Promise<void> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_experiment_results
+      (id, experiment_id, variant_id, metric, value,
+       sample_size, confidence_low, confidence_high, computed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      result.id,
+      result.experimentId,
+      result.variantId,
+      result.metric,
+      result.value,
+      result.sampleSize,
+      result.confidenceLow,
+      result.confidenceHigh,
+      result.computedAt,
+    ],
+  });
+}
+
+export async function getExperimentResults(
+  experimentId: string,
+): Promise<ExperimentMetricResult[]> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM agent_experiment_results
+      WHERE experiment_id = ?
+      ORDER BY computed_at DESC`,
+    args: [experimentId],
+  });
+  return (rows as any[]).map(rowToExperimentResult);
+}
+
+// ─── Aggregate queries for dashboard ─────────────────────────────────
+
+export async function getObservabilityOverview(
+  sinceMs: number,
+  opts: { userId?: string } = {},
+): Promise<{
+  totalRuns: number;
+  totalCostCents: number;
+  avgDurationMs: number;
+  toolSuccessRate: number;
+  avgFrustrationScore: number;
+  thumbsUpRate: number;
+  avgEvalScore: number;
+}> {
+  await ensureObservabilityTables();
+  const client = getDbExec();
+
+  // Three of the four sub-queries time-key on `created_at`; satisfaction
+  // uses `computed_at`. Each gets its own `withUserFilter` invocation so
+  // the args array isn't aliased across calls (some drivers mutate args
+  // for prepared-statement caching).
+  const created = withUserFilter("created_at >= ?", [sinceMs], opts.userId);
+  const computed = withUserFilter("computed_at >= ?", [sinceMs], opts.userId);
+
+  const [tracesResult, satisfactionResult, feedbackResult, evalsResult] =
+    await Promise.all([
+      client.execute({
+        sql: `SELECT
+          COUNT(*) as total_runs,
+          COALESCE(SUM(total_cost_cents_x100), 0) as total_cost,
+          COALESCE(AVG(total_duration_ms), 0) as avg_duration,
+          COALESCE(SUM(successful_tools), 0) as success_tools,
+          COALESCE(SUM(tool_calls), 0) as total_tools
+          FROM agent_trace_summaries WHERE ${created.where}`,
+        args: created.args,
+      }),
+      client.execute({
+        sql: `SELECT COALESCE(AVG(frustration_score), 0) as avg_frustration
+          FROM agent_satisfaction_scores WHERE ${computed.where}`,
+        args: computed.args,
+      }),
+      client.execute({
+        sql: `SELECT
+          COALESCE(SUM(CASE WHEN feedback_type = 'thumbs_up' THEN 1 ELSE 0 END), 0) as up,
+          COALESCE(SUM(CASE WHEN feedback_type IN ('thumbs_up', 'thumbs_down') THEN 1 ELSE 0 END), 0) as total
+          FROM agent_feedback WHERE ${created.where}`,
+        args: created.args,
+      }),
+      client.execute({
+        sql: `SELECT COALESCE(AVG(score), 0) as avg_score
+          FROM agent_evals WHERE ${created.where}`,
+        args: created.args,
+      }),
+    ]);
+
+  const t = (tracesResult.rows[0] ?? {}) as Record<string, number | null>;
+  const s = (satisfactionResult.rows[0] ?? {}) as Record<string, number | null>;
+  const f = (feedbackResult.rows[0] ?? {}) as Record<string, number | null>;
+  const e = (evalsResult.rows[0] ?? {}) as Record<string, number | null>;
+
+  const totalTools = Number(t.total_tools ?? 0);
+  const successTools = Number(t.success_tools ?? 0);
+  const feedbackTotal = Number(f.total ?? 0);
+  const feedbackUp = Number(f.up ?? 0);
+
+  return {
+    totalRuns: Number(t.total_runs ?? 0),
+    totalCostCents: Number(t.total_cost ?? 0) / 100,
+    avgDurationMs: Number(t.avg_duration ?? 0),
+    toolSuccessRate: totalTools > 0 ? successTools / totalTools : 1,
+    avgFrustrationScore: Number(s.avg_frustration ?? 0),
+    thumbsUpRate: feedbackTotal > 0 ? feedbackUp / feedbackTotal : 0,
+    avgEvalScore: Number(e.avg_score ?? 0),
+  };
+}
+
+// ─── Row mappers ─────────────────────────────────────────────────────
+
+function rowToTraceSpan(row: Record<string, any>): TraceSpan {
+  return {
+    id: String(row.id),
+    runId: String(row.run_id),
+    threadId: row.thread_id ? String(row.thread_id) : null,
+    userId: row.user_id ? String(row.user_id) : null,
+    parentSpanId: row.parent_span_id ? String(row.parent_span_id) : null,
+    spanType: row.span_type as TraceSpan["spanType"],
+    name: String(row.name),
+    inputTokens: Number(row.input_tokens ?? 0),
+    outputTokens: Number(row.output_tokens ?? 0),
+    cacheReadTokens: Number(row.cache_read_tokens ?? 0),
+    cacheWriteTokens: Number(row.cache_write_tokens ?? 0),
+    costCentsX100: Number(row.cost_cents_x100 ?? 0),
+    durationMs: Number(row.duration_ms ?? 0),
+    status: row.status as TraceSpan["status"],
+    errorMessage: row.error_message ? String(row.error_message) : null,
+    metadata: safeJsonParse(row.metadata, null),
+    createdAt: Number(row.created_at),
+  };
+}
+
+function rowToTraceSummary(row: Record<string, any>): TraceSummary {
+  return {
+    runId: String(row.run_id),
+    threadId: row.thread_id ? String(row.thread_id) : null,
+    userId: row.user_id ? String(row.user_id) : null,
+    totalSpans: Number(row.total_spans ?? 0),
+    llmCalls: Number(row.llm_calls ?? 0),
+    toolCalls: Number(row.tool_calls ?? 0),
+    successfulTools: Number(row.successful_tools ?? 0),
+    failedTools: Number(row.failed_tools ?? 0),
+    totalDurationMs: Number(row.total_duration_ms ?? 0),
+    totalCostCentsX100: Number(row.total_cost_cents_x100 ?? 0),
+    totalInputTokens: Number(row.total_input_tokens ?? 0),
+    totalOutputTokens: Number(row.total_output_tokens ?? 0),
+    model: String(row.model ?? ""),
+    createdAt: Number(row.created_at),
+  };
+}
+
+function rowToFeedback(row: Record<string, any>): FeedbackEntry {
+  return {
+    id: String(row.id),
+    runId: row.run_id ? String(row.run_id) : null,
+    threadId: row.thread_id ? String(row.thread_id) : null,
+    messageSeq: row.message_seq != null ? Number(row.message_seq) : null,
+    feedbackType: row.feedback_type as FeedbackEntry["feedbackType"],
+    value: String(row.value ?? ""),
+    userId: row.user_id ? String(row.user_id) : null,
+    createdAt: Number(row.created_at),
+  };
+}
+
+function rowToSatisfaction(row: Record<string, any>): SatisfactionScore {
+  return {
+    id: String(row.id),
+    threadId: String(row.thread_id),
+    userId: row.user_id ? String(row.user_id) : null,
+    frustrationScore: Number(row.frustration_score ?? 0),
+    rephrasingScore: Number(row.rephrasing_score ?? 0),
+    abandonmentScore: Number(row.abandonment_score ?? 0),
+    sentimentScore: Number(row.sentiment_score ?? 0),
+    lengthTrendScore: Number(row.length_trend_score ?? 0),
+    computedAt: Number(row.computed_at),
+  };
+}
+
+function rowToEval(row: Record<string, any>): EvalResult {
+  return {
+    id: String(row.id),
+    runId: String(row.run_id),
+    threadId: row.thread_id ? String(row.thread_id) : null,
+    userId: row.user_id ? String(row.user_id) : null,
+    evalType: row.eval_type as EvalResult["evalType"],
+    criteria: String(row.criteria),
+    score: Number(row.score ?? 0),
+    reasoning: row.reasoning ? String(row.reasoning) : null,
+    metadata: safeJsonParse(row.metadata, null),
+    createdAt: Number(row.created_at),
+  };
+}
+
+function rowToDataset(row: Record<string, any>): EvalDataset {
+  return {
+    id: String(row.id),
+    name: String(row.name),
+    description: String(row.description ?? ""),
+    entries: safeJsonParse(row.entries, []),
+    createdAt: Number(row.created_at),
+    updatedAt: Number(row.updated_at),
+  };
+}
+
+function rowToExperiment(row: Record<string, any>): Experiment {
+  return {
+    id: String(row.id),
+    name: String(row.name),
+    status: row.status as Experiment["status"],
+    variants: safeJsonParse(row.variants, []),
+    metrics: safeJsonParse(row.metrics, []),
+    assignmentLevel: (row.assignment_level as "user" | "session") ?? "user",
+    startedAt: row.started_at ? Number(row.started_at) : null,
+    endedAt: row.ended_at ? Number(row.ended_at) : null,
+    createdAt: Number(row.created_at),
+    ownerEmail:
+      typeof row.owner_email === "string" && row.owner_email
+        ? row.owner_email
+        : null,
+  };
+}
+
+function rowToExperimentResult(
+  row: Record<string, any>,
+): ExperimentMetricResult {
+  return {
+    id: String(row.id),
+    experimentId: String(row.experiment_id),
+    variantId: String(row.variant_id),
+    metric: String(row.metric),
+    value: Number(row.value ?? 0),
+    sampleSize: Number(row.sample_size ?? 0),
+    confidenceLow: Number(row.confidence_low ?? 0),
+    confidenceHigh: Number(row.confidence_high ?? 0),
+    computedAt: Number(row.computed_at),
+  };
+}