@axiom-lattice/pg-stores 1.0.53 → 1.0.55

package/src/stores/PostgreSQLEvalStore.ts

@@ -0,0 +1,880 @@
+/**
+ * PostgreSQL implementation of EvalStore
+ */
+
+import { Pool } from "pg";
+import type { PoolConfig } from "pg";
+import {
+  EvalStore,
+  EvalProject,
+  CreateEvalProjectRequest,
+  EvalSuite,
+  CreateEvalSuiteRequest,
+  EvalCase,
+  CreateEvalCaseRequest,
+  EvalRun,
+  CreateEvalRunRequest,
+  EvalRunResult,
+  EvalProjectReport,
+} from "@axiom-lattice/protocols";
+import { MigrationManager } from "../migrations/migration";
+import { evalMigrations } from "../migrations/eval_migrations";
+import { v4 as uuidv4 } from "uuid";
+
+/** PostgreSQL EvalStore options */
+export interface PostgreSQLEvalStoreOptions {
+  /** PostgreSQL connection pool configuration */
+  poolConfig: string | PoolConfig;
+  /** Whether to run migrations automatically on initialization @default true */
+  autoMigrate?: boolean;
+}
+
+/**
+ * PostgreSQL implementation of EvalStore
+ *
+ * Features:
+ * - Multi-tenant isolation via tenant_id
+ * - Full CRUD for projects, suites, cases, runs, run results
+ * - Project report aggregation
+ */
+export class PostgreSQLEvalStore implements EvalStore {
+  private pool: Pool;
+  private migrationManager: MigrationManager;
+  private initialized: boolean = false;
+  private ownsPool: boolean = true;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(options: PostgreSQLEvalStoreOptions) {
+    // Create Pool from config
+    if (typeof options.poolConfig === "string") {
+      this.pool = new Pool({ connectionString: options.poolConfig });
+    } else {
+      this.pool = new Pool(options.poolConfig);
+    }
+
+    this.migrationManager = new MigrationManager(this.pool);
+    for (const m of evalMigrations) {
+      this.migrationManager.register(m);
+    }
+
+    // Auto-migrate by default
+    if (options.autoMigrate !== false) {
+      this.initialize().catch((error) => {
+        console.error("Failed to initialize PostgreSQLEvalStore:", error);
+        throw error;
+      });
+    }
+  }
+
+  /** Dispose resources and close the connection pool */
+  async dispose(): Promise<void> {
+    if (this.ownsPool && this.pool) {
+      await this.pool.end();
+    }
+  }
+
+  /**
+   * Initialize the store and run migrations
+   * Uses a promise-based lock to prevent concurrent initialization
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+
+    this.initPromise = (async () => {
+      try {
+        await this.migrationManager.migrate();
+        this.initialized = true;
+      } finally {
+        this.initPromise = null;
+      }
+    })();
+
+    return this.initPromise;
+  }
+
+  /** Ensure store is initialized */
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Row mappers
+  // ---------------------------------------------------------------------------
+
+  private mapRowToProject(row: Record<string, unknown>): EvalProject {
+    return {
+      id: row.id as string,
+      tenantId: row.tenant_id as string,
+      name: row.name as string,
+      description: row.description as string | undefined,
+      version: row.version as string | undefined,
+      judgeModelConfig: this.parseRequiredJson<Record<string, unknown>>(row.judge_model_config, {}),
+      targetServerConfig: this.parseRequiredJson<Record<string, unknown>>(row.target_server_config, {}),
+      concurrency: (row.concurrency as number) ?? 3,
+      reportConfig: this.parseOptionalJson<Record<string, unknown>>(row.report_config),
+      createdAt: new Date(row.created_at as string),
+      updatedAt: new Date(row.updated_at as string),
+    };
+  }
+
+  private mapRowToSuite(row: Record<string, unknown>): EvalSuite {
+    return {
+      id: row.id as string,
+      tenantId: row.tenant_id as string,
+      projectId: row.project_id as string,
+      name: row.name as string,
+      createdAt: new Date(row.created_at as string),
+      updatedAt: new Date(row.updated_at as string),
+      caseCount: row.case_count !== undefined ? (row.case_count as number) : undefined,
+    };
+  }
+
+  private mapRowToCase(row: Record<string, unknown>): EvalCase {
+    return {
+      id: row.id as string,
+      tenantId: row.tenant_id as string,
+      suiteId: row.suite_id as string,
+      inputMessage: row.input_message as string,
+      inputFiles: this.parseOptionalJson<Record<string, string>>(row.input_files),
+      steps: this.parseRequiredJson<Array<{ agent_id: string; override_message?: string }>>(row.steps, []),
+      outputType: (row.output_type as EvalCase["outputType"]) || "message_content",
+      contentAssertion: (row.content_assertion as string) || "",
+      rubrics: this.parseOptionalJson<Array<{ name: string; weight: number; description: string }>>(row.rubrics),
+      createdAt: new Date(row.created_at as string),
+      updatedAt: new Date(row.updated_at as string),
+    };
+  }
+
+  private mapRowToRun(row: Record<string, unknown>): EvalRun {
+    return {
+      id: row.id as string,
+      projectId: row.project_id as string,
+      tenantId: row.tenant_id as string,
+      status: row.status as EvalRun["status"],
+      concurrency: (row.concurrency as number) ?? 3,
+      totalCases: (row.total_cases as number) ?? 0,
+      passedCases: (row.passed_cases as number) ?? 0,
+      failedCases: (row.failed_cases as number) ?? 0,
+      avgScore: (row.avg_score as number) ?? 0,
+      error: row.error as string | undefined,
+      createdAt: new Date(row.created_at as string),
+      startedAt: row.started_at ? new Date(row.started_at as string) : undefined,
+      completedAt: row.completed_at ? new Date(row.completed_at as string) : undefined,
+    };
+  }
+
+  private mapRowToRunResult(row: Record<string, unknown>): EvalRunResult {
+    return {
+      id: row.id as string,
+      runId: row.run_id as string,
+      suiteName: row.suite_name as string,
+      caseId: row.case_id as string | undefined,
+      pass: (row.pass as boolean) ?? false,
+      score: (row.score as number) ?? 0,
+      summary: row.summary as string | undefined,
+      dimensionResults: this.parseOptionalJson<Array<{ name: string; score: number; reason: string }>>(row.dimension_results),
+      durationMs: row.duration_ms as number | undefined,
+      messages: this.parseOptionalJson<Array<{ role: string; content: string; id?: string }>>(row.messages),
+      logs: this.parseOptionalJson<Array<{ timestamp: string; level: string; message: string; data?: unknown }>>(row.logs),
+      error: row.error as string | undefined,
+      createdAt: new Date(row.created_at as string),
+    };
+  }
+
+  private parseRequiredJson<T>(val: unknown, fallback: T): T {
+    if (val == null) return fallback;
+    if (typeof val === "string") {
+      try {
+        return JSON.parse(val) as T;
+      } catch {
+        return fallback;
+      }
+    }
+    return val as T;
+  }
+
+  private parseOptionalJson<T>(val: unknown): T | undefined {
+    if (val == null) return undefined;
+    if (typeof val === "string") {
+      try {
+        return JSON.parse(val) as T;
+      } catch {
+        return undefined;
+      }
+    }
+    return val as T;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Projects
+  // ---------------------------------------------------------------------------
+
+  /** Get all eval projects for a tenant */
+  async getProjectsByTenant(tenantId: string): Promise<EvalProject[]> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; name: string; description: string | null;
+      version: string | null; judge_model_config: unknown; target_server_config: unknown;
+      concurrency: number; report_config: unknown; created_at: string; updated_at: string;
+    }>(
+      `SELECT id, tenant_id, name, description, version,
+              judge_model_config, target_server_config, concurrency,
+              report_config, created_at, updated_at
+       FROM lattice_eval_projects
+       WHERE tenant_id = $1
+       ORDER BY created_at DESC`,
+      [tenantId]
+    );
+    return rows.map((r) => this.mapRowToProject(r as unknown as Record<string, unknown>));
+  }
+
+  /** Get a single eval project by ID for a tenant */
+  async getProjectById(tenantId: string, id: string): Promise<EvalProject | null> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; name: string; description: string | null;
+      version: string | null; judge_model_config: unknown; target_server_config: unknown;
+      concurrency: number; report_config: unknown; created_at: string; updated_at: string;
+    }>(
+      `SELECT id, tenant_id, name, description, version,
+              judge_model_config, target_server_config, concurrency,
+              report_config, created_at, updated_at
+       FROM lattice_eval_projects
+       WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+    return rows.length ? this.mapRowToProject(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Create a new eval project */
+  async createProject(
+    tenantId: string,
+    id: string,
+    data: CreateEvalProjectRequest
+  ): Promise<EvalProject> {
+    await this.ensureInitialized();
+    const actualId = id || uuidv4();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; name: string; description: string | null;
+      version: string | null; judge_model_config: unknown; target_server_config: unknown;
+      concurrency: number; report_config: unknown; created_at: string; updated_at: string;
+    }>(
+      `INSERT INTO lattice_eval_projects
+        (id, tenant_id, name, description, version, judge_model_config, target_server_config, concurrency, report_config)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       RETURNING id, tenant_id, name, description, version,
+                 judge_model_config, target_server_config, concurrency,
+                 report_config, created_at, updated_at`,
+      [
+        actualId,
+        tenantId,
+        data.name,
+        data.description || null,
+        data.version || null,
+        JSON.stringify(data.judgeModelConfig),
+        JSON.stringify(data.targetServerConfig),
+        data.concurrency ?? 3,
+        data.reportConfig === undefined ? null : JSON.stringify(data.reportConfig),
+      ]
+    );
+    return this.mapRowToProject(rows[0] as unknown as Record<string, unknown>);
+  }
+
+  /** Update an eval project */
+  async updateProject(
+    tenantId: string,
+    id: string,
+    updates: Partial<CreateEvalProjectRequest>
+  ): Promise<EvalProject | null> {
+    await this.ensureInitialized();
+    const set: string[] = [];
+    const vals: unknown[] = [];
+    let i = 1;
+    if (updates.name !== undefined) { set.push(`name = $${i++}`); vals.push(updates.name); }
+    if (updates.description !== undefined) { set.push(`description = $${i++}`); vals.push(updates.description); }
+    if (updates.version !== undefined) { set.push(`version = $${i++}`); vals.push(updates.version); }
+    if (updates.judgeModelConfig !== undefined) { set.push(`judge_model_config = $${i++}`); vals.push(JSON.stringify(updates.judgeModelConfig)); }
+    if (updates.targetServerConfig !== undefined) { set.push(`target_server_config = $${i++}`); vals.push(JSON.stringify(updates.targetServerConfig)); }
+    if (updates.concurrency !== undefined) { set.push(`concurrency = $${i++}`); vals.push(updates.concurrency); }
+    if (updates.reportConfig !== undefined) { set.push(`report_config = $${i++}`); vals.push(JSON.stringify(updates.reportConfig)); }
+    if (set.length === 0) return this.getProjectById(tenantId, id);
+    set.push(`updated_at = NOW()`);
+    vals.push(id, tenantId);
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; name: string; description: string | null;
+      version: string | null; judge_model_config: unknown; target_server_config: unknown;
+      concurrency: number; report_config: unknown; created_at: string; updated_at: string;
+    }>(
+      `UPDATE lattice_eval_projects SET ${set.join(", ")}
+       WHERE id = $${i} AND tenant_id = $${i + 1}
+       RETURNING id, tenant_id, name, description, version,
+                 judge_model_config, target_server_config, concurrency,
+                 report_config, created_at, updated_at`,
+      vals
+    );
+    return rows.length ? this.mapRowToProject(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Delete an eval project */
+  async deleteProject(tenantId: string, id: string): Promise<boolean> {
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `DELETE FROM lattice_eval_projects WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Suites
+  // ---------------------------------------------------------------------------
+
+  /** Get all suites in a project with case counts */
+  async getSuitesByProject(tenantId: string, projectId: string): Promise<EvalSuite[]> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; project_id: string; name: string;
+      created_at: string; updated_at: string; case_count: number;
+    }>(
+      `SELECT s.id, s.tenant_id, s.project_id, s.name, s.created_at, s.updated_at,
+              COUNT(c.id)::int AS case_count
+       FROM lattice_eval_suites s
+       LEFT JOIN lattice_eval_cases c ON c.suite_id = s.id
+       WHERE s.tenant_id = $1 AND s.project_id = $2
+       GROUP BY s.id
+       ORDER BY s.created_at DESC`,
+      [tenantId, projectId]
+    );
+    return rows.map((r) => this.mapRowToSuite(r as unknown as Record<string, unknown>));
+  }
+
+  /** Get a single suite by ID with case count */
+  async getSuiteById(tenantId: string, id: string): Promise<EvalSuite | null> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; project_id: string; name: string;
+      created_at: string; updated_at: string; case_count: number;
+    }>(
+      `SELECT s.id, s.tenant_id, s.project_id, s.name, s.created_at, s.updated_at,
+              COUNT(c.id)::int AS case_count
+       FROM lattice_eval_suites s
+       LEFT JOIN lattice_eval_cases c ON c.suite_id = s.id
+       WHERE s.tenant_id = $1 AND s.id = $2
+       GROUP BY s.id`,
+      [tenantId, id]
+    );
+    return rows.length ? this.mapRowToSuite(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Create a new eval suite */
+  async createSuite(
+    tenantId: string,
+    projectId: string,
+    id: string,
+    data: CreateEvalSuiteRequest
+  ): Promise<EvalSuite> {
+    await this.ensureInitialized();
+    const actualId = id || uuidv4();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; project_id: string; name: string;
+      created_at: string; updated_at: string;
+    }>(
+      `INSERT INTO lattice_eval_suites (id, tenant_id, project_id, name)
+       VALUES ($1, $2, $3, $4)
+       RETURNING id, tenant_id, project_id, name, created_at, updated_at`,
+      [actualId, tenantId, projectId, data.name]
+    );
+    return this.mapRowToSuite(rows[0] as unknown as Record<string, unknown>);
+  }
+
+  /** Update a suite's name */
+  async updateSuite(
+    tenantId: string,
+    id: string,
+    updates: Partial<CreateEvalSuiteRequest>
+  ): Promise<EvalSuite | null> {
+    await this.ensureInitialized();
+    const set: string[] = [];
+    const vals: unknown[] = [];
+    let i = 1;
+    if (updates.name !== undefined) { set.push(`name = $${i++}`); vals.push(updates.name); }
+    if (set.length === 0) return this.getSuiteById(tenantId, id);
+    set.push(`updated_at = NOW()`);
+    vals.push(id, tenantId);
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; project_id: string; name: string;
+      created_at: string; updated_at: string;
+    }>(
+      `UPDATE lattice_eval_suites SET ${set.join(", ")}
+       WHERE id = $${i} AND tenant_id = $${i + 1}
+       RETURNING id, tenant_id, project_id, name, created_at, updated_at`,
+      vals
+    );
+    return rows.length ? this.mapRowToSuite(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Delete a suite */
+  async deleteSuite(tenantId: string, id: string): Promise<boolean> {
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `DELETE FROM lattice_eval_suites WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Cases
+  // ---------------------------------------------------------------------------
+
+  /** Get all test cases in a suite */
+  async getCasesBySuite(tenantId: string, suiteId: string): Promise<EvalCase[]> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; suite_id: string;
+      input_message: string; input_files: unknown; steps: unknown;
+      output_type: string; content_assertion: string; rubrics: unknown;
+      created_at: string; updated_at: string;
+    }>(
+      `SELECT id, tenant_id, suite_id,
+              input_message, input_files, steps,
+              output_type, content_assertion, rubrics,
+              created_at, updated_at
+       FROM lattice_eval_cases
+       WHERE tenant_id = $1 AND suite_id = $2
+       ORDER BY created_at`,
+      [tenantId, suiteId]
+    );
+    return rows.map((r) => this.mapRowToCase(r as unknown as Record<string, unknown>));
+  }
+
+  /** Get a single test case by ID */
+  async getCaseById(tenantId: string, id: string): Promise<EvalCase | null> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; suite_id: string;
+      input_message: string; input_files: unknown; steps: unknown;
+      output_type: string; content_assertion: string; rubrics: unknown;
+      created_at: string; updated_at: string;
+    }>(
+      `SELECT id, tenant_id, suite_id,
+              input_message, input_files, steps,
+              output_type, content_assertion, rubrics,
+              created_at, updated_at
+       FROM lattice_eval_cases
+       WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+    return rows.length ? this.mapRowToCase(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Create a new test case */
+  async createCase(
+    tenantId: string,
+    suiteId: string,
+    id: string,
+    data: CreateEvalCaseRequest
+  ): Promise<EvalCase> {
+    await this.ensureInitialized();
+    const actualId = id || uuidv4();
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; suite_id: string;
+      input_message: string; input_files: unknown; steps: unknown;
+      output_type: string; content_assertion: string; rubrics: unknown;
+      created_at: string; updated_at: string;
+    }>(
+      `INSERT INTO lattice_eval_cases
+        (id, tenant_id, suite_id, input_message, input_files, steps, output_type, content_assertion, rubrics)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       RETURNING id, tenant_id, suite_id,
+                 input_message, input_files, steps,
+                 output_type, content_assertion, rubrics,
+                 created_at, updated_at`,
+      [
+        actualId,
+        tenantId,
+        suiteId,
+        data.inputMessage,
+        JSON.stringify(data.inputFiles || {}),
+        JSON.stringify(data.steps),
+        data.outputType,
+        data.contentAssertion || null,
+        JSON.stringify(data.rubrics || []),
+      ]
+    );
+    return this.mapRowToCase(rows[0] as unknown as Record<string, unknown>);
+  }
+
+  /** Update a test case */
+  async updateCase(
+    tenantId: string,
+    id: string,
+    updates: Partial<CreateEvalCaseRequest>
+  ): Promise<EvalCase | null> {
+    await this.ensureInitialized();
+    const set: string[] = [];
+    const vals: unknown[] = [];
+    let i = 1;
+    if (updates.inputMessage !== undefined) { set.push(`input_message = $${i++}`); vals.push(updates.inputMessage); }
+    if (updates.inputFiles !== undefined) { set.push(`input_files = $${i++}`); vals.push(JSON.stringify(updates.inputFiles)); }
+    if (updates.steps !== undefined) { set.push(`steps = $${i++}`); vals.push(JSON.stringify(updates.steps)); }
+    if (updates.outputType !== undefined) { set.push(`output_type = $${i++}`); vals.push(updates.outputType); }
+    if (updates.contentAssertion !== undefined) { set.push(`content_assertion = $${i++}`); vals.push(updates.contentAssertion); }
+    if (updates.rubrics !== undefined) { set.push(`rubrics = $${i++}`); vals.push(JSON.stringify(updates.rubrics)); }
+    if (set.length === 0) return this.getCaseById(tenantId, id);
+    set.push(`updated_at = NOW()`);
+    vals.push(id, tenantId);
+    const { rows } = await this.pool.query<{
+      id: string; tenant_id: string; suite_id: string;
+      input_message: string; input_files: unknown; steps: unknown;
+      output_type: string; content_assertion: string; rubrics: unknown;
+      created_at: string; updated_at: string;
+    }>(
+      `UPDATE lattice_eval_cases SET ${set.join(", ")}
+       WHERE id = $${i} AND tenant_id = $${i + 1}
+       RETURNING id, tenant_id, suite_id,
+                 input_message, input_files, steps,
+                 output_type, content_assertion, rubrics,
+                 created_at, updated_at`,
+      vals
+    );
+    return rows.length ? this.mapRowToCase(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Delete a test case */
+  async deleteCase(tenantId: string, id: string): Promise<boolean> {
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `DELETE FROM lattice_eval_cases WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Runs
+  // ---------------------------------------------------------------------------
+
+  /** Get all runs for a tenant, optionally filtered by project or status */
+  async getRunsByTenant(
+    tenantId: string,
+    opts?: { projectId?: string; status?: string }
+  ): Promise<EvalRun[]> {
+    await this.ensureInitialized();
+    const conditions: string[] = ["tenant_id = $1"];
+    const vals: unknown[] = [tenantId];
+    let i = 2;
+    if (opts?.projectId) { conditions.push(`project_id = $${i++}`); vals.push(opts.projectId); }
+    if (opts?.status) { conditions.push(`status = $${i++}`); vals.push(opts.status); }
+    const { rows } = await this.pool.query<{
+      id: string; project_id: string; tenant_id: string;
+      status: string; concurrency: number; total_cases: number;
+      passed_cases: number; failed_cases: number; avg_score: number;
+      error: string | null; created_at: string; started_at: string | null;
+      completed_at: string | null;
+    }>(
+      `SELECT id, project_id, tenant_id,
+              status, concurrency, total_cases,
+              passed_cases, failed_cases, avg_score,
+              error, created_at, started_at, completed_at
+       FROM lattice_eval_runs
+       WHERE ${conditions.join(" AND ")}
+       ORDER BY created_at DESC`,
+      vals
+    );
+    return rows.map((r) => this.mapRowToRun(r as unknown as Record<string, unknown>));
+  }
+
+  /** Get a single run by ID */
+  async getRunById(tenantId: string, id: string): Promise<EvalRun | null> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; project_id: string; tenant_id: string;
+      status: string; concurrency: number; total_cases: number;
+      passed_cases: number; failed_cases: number; avg_score: number;
+      error: string | null; created_at: string; started_at: string | null;
+      completed_at: string | null;
+    }>(
+      `SELECT id, project_id, tenant_id,
+              status, concurrency, total_cases,
+              passed_cases, failed_cases, avg_score,
+              error, created_at, started_at, completed_at
+       FROM lattice_eval_runs
+       WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+    return rows.length ? this.mapRowToRun(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Create a new eval run */
+  async createRun(
+    tenantId: string,
+    projectId: string,
+    id: string,
+    data: CreateEvalRunRequest
+  ): Promise<EvalRun> {
+    await this.ensureInitialized();
+    const actualId = id || uuidv4();
+    const { rows } = await this.pool.query<{
+      id: string; project_id: string; tenant_id: string;
+      status: string; concurrency: number; total_cases: number;
+      passed_cases: number; failed_cases: number; avg_score: number;
+      error: string | null; created_at: string; started_at: string | null;
+      completed_at: string | null;
+    }>(
+      `INSERT INTO lattice_eval_runs
+        (id, project_id, tenant_id, status, concurrency, total_cases, passed_cases, failed_cases, avg_score, started_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       RETURNING id, project_id, tenant_id,
+                 status, concurrency, total_cases,
+                 passed_cases, failed_cases, avg_score,
+                 error, created_at, started_at, completed_at`,
+      [
+        actualId,
+        projectId,
+        tenantId,
+        "running",
+        data.concurrency,
+        data.totalCases,
+        0,
+        0,
+        0,
+        new Date(),
+      ]
+    );
+    return this.mapRowToRun(rows[0] as unknown as Record<string, unknown>);
+  }
+
+  /** Update a run's status and aggregate fields */
+  async updateRunStatus(
+    tenantId: string,
+    id: string,
+    updates: {
+      status?: EvalRun["status"];
+      passedCases?: number;
+      failedCases?: number;
+      avgScore?: number;
+      error?: string;
+      completedAt?: Date;
+    }
+  ): Promise<EvalRun | null> {
+    await this.ensureInitialized();
+    const set: string[] = [];
+    const vals: unknown[] = [];
+    let i = 1;
+    if (updates.status !== undefined) { set.push(`status = $${i++}`); vals.push(updates.status); }
+    if (updates.passedCases !== undefined) { set.push(`passed_cases = $${i++}`); vals.push(updates.passedCases); }
+    if (updates.failedCases !== undefined) { set.push(`failed_cases = $${i++}`); vals.push(updates.failedCases); }
+    if (updates.avgScore !== undefined) { set.push(`avg_score = $${i++}`); vals.push(updates.avgScore); }
+    if (updates.completedAt !== undefined) { set.push(`completed_at = $${i++}`); vals.push(updates.completedAt); }
+    if (updates.error !== undefined) { set.push(`error = $${i++}`); vals.push(updates.error); }
+    if (set.length === 0) return this.getRunById(tenantId, id);
+    vals.push(id, tenantId);
+    const { rows } = await this.pool.query<{
+      id: string; project_id: string; tenant_id: string;
+      status: string; concurrency: number; total_cases: number;
+      passed_cases: number; failed_cases: number; avg_score: number;
+      error: string | null; created_at: string; started_at: string | null;
+      completed_at: string | null;
+    }>(
+      `UPDATE lattice_eval_runs SET ${set.join(", ")}
+       WHERE id = $${i} AND tenant_id = $${i + 1}
+       RETURNING id, project_id, tenant_id,
+                 status, concurrency, total_cases,
+                 passed_cases, failed_cases, avg_score,
+                 error, created_at, started_at, completed_at`,
+      vals
+    );
+    return rows.length ? this.mapRowToRun(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Delete a run and its results */
+  async deleteRun(tenantId: string, id: string): Promise<boolean> {
+    await this.ensureInitialized();
+    // Delete results first, then the run
+    await this.pool.query(`DELETE FROM lattice_eval_run_results WHERE run_id = $1 AND tenant_id = $2`, [id, tenantId]);
+    const { rowCount } = await this.pool.query(
+      `DELETE FROM lattice_eval_runs WHERE id = $1 AND tenant_id = $2`, [id, tenantId]
+    );
+    return (rowCount ?? 0) > 0;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Run Results
+  // ---------------------------------------------------------------------------
+
+  /** Get all results belonging to a run */
+  async getResultsByRun(tenantId: string, runId: string): Promise<EvalRunResult[]> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; run_id: string; suite_name: string;
+      case_id: string | null; pass: boolean; score: number;
+      summary: string | null; dimension_results: unknown;
+      duration_ms: number | null; messages: unknown; logs: unknown;
+      error: string | null; created_at: string;
+    }>(
+      `SELECT rr.id, rr.run_id, rr.suite_name, rr.case_id,
+              rr.pass, rr.score, rr.summary, rr.dimension_results,
+              rr.duration_ms, rr.messages, rr.logs, rr.error, rr.created_at
+       FROM lattice_eval_run_results rr
+       INNER JOIN lattice_eval_runs r ON r.id = rr.run_id
+       WHERE r.tenant_id = $1 AND rr.run_id = $2
+       ORDER BY rr.created_at`,
+      [tenantId, runId]
+    );
+    return rows.map((r) => this.mapRowToRunResult(r as unknown as Record<string, unknown>));
+  }
+
+  /** Create a result for a case within a run */
+  async createRunResult(
+    tenantId: string,
+    runId: string,
+    id: string,
+    data: Omit<EvalRunResult, "id" | "runId" | "createdAt">
+  ): Promise<EvalRunResult> {
+    await this.ensureInitialized();
+    const actualId = id || uuidv4();
+    const { rows } = await this.pool.query<{
+      id: string; run_id: string; suite_name: string;
+      case_id: string | null; pass: boolean; score: number;
+      summary: string | null; dimension_results: unknown;
+      duration_ms: number | null; messages: unknown; logs: unknown;
+      error: string | null; created_at: string;
+    }>(
+      `INSERT INTO lattice_eval_run_results
+        (id, run_id, suite_name, case_id, pass, score, summary, dimension_results, duration_ms, messages, logs, error)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+       RETURNING id, run_id, suite_name, case_id,
+                 pass, score, summary, dimension_results,
+                 duration_ms, messages, logs, error, created_at`,
+      [
+        actualId,
+        runId,
+        data.suiteName,
+        data.caseId || null,
+        data.pass,
+        data.score,
+        data.summary || null,
+        JSON.stringify(data.dimensionResults || []),
+        data.durationMs ?? null,
+        JSON.stringify(data.messages || []),
+        JSON.stringify(data.logs || []),
+        data.error || null,
+      ]
+    );
+    return this.mapRowToRunResult(rows[0] as unknown as Record<string, unknown>);
+  }
+
+  /** Update a run result with tenant isolation via the parent run */
+  async updateRunResult(
+    tenantId: string,
+    id: string,
+    updates: Partial<EvalRunResult>
+  ): Promise<EvalRunResult | null> {
+    await this.ensureInitialized();
+    if (updates.runId !== undefined) {
+      throw new Error("runId cannot be updated on an existing result");
+    }
+    const set: string[] = [];
+    const vals: unknown[] = [];
+    let i = 1;
+    if (updates.suiteName !== undefined) { set.push(`suite_name = $${i++}`); vals.push(updates.suiteName); }
+    if (updates.caseId !== undefined) { set.push(`case_id = $${i++}`); vals.push(updates.caseId); }
+    if (updates.pass !== undefined) { set.push(`pass = $${i++}`); vals.push(updates.pass); }
+    if (updates.score !== undefined) { set.push(`score = $${i++}`); vals.push(updates.score); }
+    if (updates.summary !== undefined) { set.push(`summary = $${i++}`); vals.push(updates.summary); }
+    if (updates.dimensionResults !== undefined) { set.push(`dimension_results = $${i++}`); vals.push(JSON.stringify(updates.dimensionResults)); }
+    if (updates.durationMs !== undefined) { set.push(`duration_ms = $${i++}`); vals.push(updates.durationMs); }
+    if (updates.messages !== undefined) { set.push(`messages = $${i++}`); vals.push(JSON.stringify(updates.messages)); }
+    if (updates.logs !== undefined) { set.push(`logs = $${i++}`); vals.push(JSON.stringify(updates.logs)); }
+    if (updates.error !== undefined) { set.push(`error = $${i++}`); vals.push(updates.error); }
+    if (set.length === 0) return this.getRunResultById(tenantId, id);
+    vals.push(id, tenantId);
+    const { rows } = await this.pool.query<{
+      id: string; run_id: string; suite_name: string;
+      case_id: string | null; pass: boolean; score: number;
+      summary: string | null; dimension_results: unknown;
+      duration_ms: number | null; messages: unknown; logs: unknown;
+      error: string | null; created_at: string;
+    }>(
+      `UPDATE lattice_eval_run_results SET ${set.join(", ")}
+       WHERE id = $${i}
+         AND run_id IN (SELECT id FROM lattice_eval_runs WHERE tenant_id = $${i + 1})
+       RETURNING id, run_id, suite_name, case_id,
+                 pass, score, summary, dimension_results,
+                 duration_ms, messages, logs, error, created_at`,
+      vals
+    );
+    return rows.length ? this.mapRowToRunResult(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  /** Get a single run result by ID with tenant isolation */
+  private async getRunResultById(tenantId: string, id: string): Promise<EvalRunResult | null> {
+    await this.ensureInitialized();
+    const { rows } = await this.pool.query<{
+      id: string; run_id: string; suite_name: string;
+      case_id: string | null; pass: boolean; score: number;
+      summary: string | null; dimension_results: unknown;
+      duration_ms: number | null; messages: unknown; logs: unknown;
+      error: string | null; created_at: string;
+    }>(
+      `SELECT rr.id, rr.run_id, rr.suite_name, rr.case_id,
+              rr.pass, rr.score, rr.summary, rr.dimension_results,
+              rr.duration_ms, rr.messages, rr.logs, rr.error, rr.created_at
+       FROM lattice_eval_run_results rr
+       INNER JOIN lattice_eval_runs r ON r.id = rr.run_id
+       WHERE rr.id = $1 AND r.tenant_id = $2`,
+      [id, tenantId]
+    );
+    return rows.length ? this.mapRowToRunResult(rows[0] as unknown as Record<string, unknown>) : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Reports
+  // ---------------------------------------------------------------------------
+
+  /** Aggregate report for a project including all runs */
+  async getProjectReport(tenantId: string, projectId: string): Promise<EvalProjectReport | null> {
+    await this.ensureInitialized();
+    const projectRows = await this.pool.query<{
+      id: string; tenant_id: string; name: string; description: string | null;
+      version: string | null; judge_model_config: unknown; target_server_config: unknown;
+      concurrency: number; report_config: unknown; created_at: string; updated_at: string;
+    }>(
+      `SELECT id, tenant_id, name, description, version,
+              judge_model_config, target_server_config, concurrency,
+              report_config, created_at, updated_at
+       FROM lattice_eval_projects
+       WHERE id = $1 AND tenant_id = $2`,
+      [projectId, tenantId]
+    );
+    if (projectRows.rows.length === 0) return null;
+
+    const project = this.mapRowToProject(projectRows.rows[0] as unknown as Record<string, unknown>);
+    const runs = await this.getRunsByTenant(tenantId, { projectId });
+    const totalRuns = runs.length;
+    const latestPassRate = runs.length > 0
+      ? (runs[0].totalCases > 0 ? runs[0].passedCases / runs[0].totalCases : 0)
+      : 0;
+    const avgScore = runs.length > 0
+      ? runs.reduce((sum, r) => sum + r.avgScore, 0) / runs.length
+      : 0;
+
+    return {
+      projectId: project.id,
+      projectName: project.name,
+      totalRuns,
+      latestPassRate,
+      avgScore,
+      runs,
+    };
+  }
+}