@mastra/clickhouse 1.4.1 → 1.5.0-alpha.1

package/dist/index.js

@@ -1,8 +1,8 @@
 import { createClient } from '@clickhouse/client';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SKILLS, TABLE_WORKSPACE_VERSIONS, TABLE_WORKSPACES, TABLE_MCP_SERVER_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SCORER_DEFINITIONS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_PROMPT_BLOCKS, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, TABLE_DATASET_VERSIONS, TABLE_DATASET_ITEMS, TABLE_DATASETS, TABLE_AGENT_VERSIONS, TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, MemoryStorage, TABLE_SCHEMAS, createStorageErrorId, normalizePerPage, calculatePagination, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, WorkflowsStorage, MastraCompositeStore, getSqlType, getDefaultValue, safelyParseJSON, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, EntityType, TraceStatus } from '@mastra/core/storage';
-import { MessageList } from '@mastra/core/agent';
+import { TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SKILLS, TABLE_WORKSPACE_VERSIONS, TABLE_WORKSPACES, TABLE_MCP_SERVER_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SCORER_DEFINITIONS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_PROMPT_BLOCKS, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, TABLE_DATASET_VERSIONS, TABLE_DATASET_ITEMS, TABLE_DATASETS, TABLE_AGENT_VERSIONS, TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, BackgroundTasksStorage, TABLE_SCHEMAS, TABLE_BACKGROUND_TASKS, MemoryStorage, createStorageErrorId, normalizePerPage, calculatePagination, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, WorkflowsStorage, MastraCompositeStore, getSqlType, getDefaultValue, safelyParseJSON, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, EntityType, TraceStatus } from '@mastra/core/storage';
 import { MastraBase } from '@mastra/core/base';
+import { MessageList } from '@mastra/core/agent';
 import { parseFieldKey } from '@mastra/core/utils';
 import { saveScorePayloadSchema } from '@mastra/core/evals';
 
@@ -37,7 +37,8 @@ var TABLE_ENGINES = {
   [TABLE_WORKSPACE_VERSIONS]: `MergeTree()`,
   [TABLE_SKILLS]: `ReplacingMergeTree()`,
   [TABLE_SKILL_VERSIONS]: `MergeTree()`,
-  [TABLE_SKILL_BLOBS]: `ReplacingMergeTree()`
+  [TABLE_SKILL_BLOBS]: `ReplacingMergeTree()`,
+  mastra_background_tasks: `ReplacingMergeTree()`
 };
 var COLUMN_TYPES = {
   text: "String",
@@ -682,7 +683,203 @@ var ClickhouseDB = class extends MastraBase {
   }
 };
 
-// src/storage/domains/memory/index.ts
+// src/storage/domains/background-tasks/index.ts
+function serializeJson(v) {
+  if (typeof v === "object" && v != null) return JSON.stringify(v);
+  return v ?? "";
+}
+function rowToTask(row) {
+  const parseJson2 = (val) => {
+    if (val == null || val === "") return void 0;
+    if (typeof val === "string") {
+      try {
+        return JSON.parse(val);
+      } catch {
+        return val;
+      }
+    }
+    return val;
+  };
+  return {
+    id: row.id,
+    status: row.status,
+    toolName: row.tool_name,
+    toolCallId: row.tool_call_id,
+    args: parseJson2(row.args) ?? {},
+    agentId: row.agent_id,
+    threadId: row.thread_id || void 0,
+    resourceId: row.resource_id || void 0,
+    runId: row.run_id ?? "",
+    result: parseJson2(row.result),
+    error: parseJson2(row.error),
+    retryCount: Number(row.retry_count ?? 0),
+    maxRetries: Number(row.max_retries ?? 0),
+    timeoutMs: Number(row.timeout_ms ?? 3e5),
+    createdAt: new Date(row.createdAt),
+    startedAt: row.startedAt ? new Date(row.startedAt) : void 0,
+    completedAt: row.completedAt ? new Date(row.completedAt) : void 0
+  };
+}
+var BackgroundTasksStorageClickhouse = class extends BackgroundTasksStorage {
+  client;
+  #db;
+  constructor(config) {
+    super();
+    const { client, ttl } = resolveClickhouseConfig(config);
+    this.client = client;
+    this.#db = new ClickhouseDB({ client, ttl });
+  }
+  async init() {
+    await this.#db.createTable({ tableName: TABLE_BACKGROUND_TASKS, schema: TABLE_SCHEMAS[TABLE_BACKGROUND_TASKS] });
+  }
+  async dangerouslyClearAll() {
+    await this.#db.clearTable({ tableName: TABLE_BACKGROUND_TASKS });
+  }
+  async createTask(task) {
+    await this.client.insert({
+      table: TABLE_BACKGROUND_TASKS,
+      values: [
+        {
+          id: task.id,
+          tool_call_id: task.toolCallId,
+          tool_name: task.toolName,
+          agent_id: task.agentId,
+          thread_id: task.threadId ?? "",
+          resource_id: task.resourceId ?? "",
+          run_id: task.runId,
+          status: task.status,
+          args: serializeJson(task.args),
+          result: serializeJson(task.result),
+          error: serializeJson(task.error),
+          retry_count: task.retryCount,
+          max_retries: task.maxRetries,
+          timeout_ms: task.timeoutMs,
+          createdAt: task.createdAt.toISOString(),
+          startedAt: task.startedAt?.toISOString() ?? "1970-01-01T00:00:00.000Z",
+          completedAt: task.completedAt?.toISOString() ?? "1970-01-01T00:00:00.000Z"
+        }
+      ],
+      format: "JSONEachRow",
+      clickhouse_settings: { date_time_input_format: "best_effort" }
+    });
+  }
+  async updateTask(taskId, update) {
+    const existing = await this.getTask(taskId);
+    if (!existing) return;
+    const merged = { ...existing };
+    if ("status" in update) merged.status = update.status;
+    if ("result" in update) merged.result = update.result;
+    if ("error" in update) merged.error = update.error;
+    if ("retryCount" in update) merged.retryCount = update.retryCount;
+    if ("startedAt" in update) merged.startedAt = update.startedAt;
+    if ("completedAt" in update) merged.completedAt = update.completedAt;
+    await this.createTask(merged);
+  }
+  async getTask(taskId) {
+    const result = await this.client.query({
+      query: `SELECT * FROM ${TABLE_BACKGROUND_TASKS} FINAL WHERE id = {var_id:String} LIMIT 1`,
+      query_params: { var_id: taskId },
+      format: "JSONEachRow",
+      clickhouse_settings: { date_time_input_format: "best_effort" }
+    });
+    const rows = await result.json();
+    return rows.length > 0 ? rowToTask(rows[0]) : null;
+  }
+  async listTasks(filter) {
+    const conditions = [];
+    const params = {};
+    if (filter.status) {
+      const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+      conditions.push(`status IN ({var_statuses:Array(String)})`);
+      params.var_statuses = statuses;
+    }
+    if (filter.agentId) {
+      conditions.push(`agent_id = {var_agent:String}`);
+      params.var_agent = filter.agentId;
+    }
+    if (filter.threadId) {
+      conditions.push(`thread_id = {var_thread:String}`);
+      params.var_thread = filter.threadId;
+    }
+    if (filter.runId) {
+      conditions.push(`run_id = {var_run:String}`);
+      params.var_run = filter.runId;
+    }
+    if (filter.toolName) {
+      conditions.push(`tool_name = {var_tool:String}`);
+      params.var_tool = filter.toolName;
+    }
+    const dateCol = filter.dateFilterBy === "startedAt" ? "startedAt" : filter.dateFilterBy === "completedAt" ? "completedAt" : "createdAt";
+    if (filter.fromDate) {
+      conditions.push(`${dateCol} >= parseDateTimeBestEffort({var_from_date:String})`);
+      params.var_from_date = filter.fromDate.toISOString();
+    }
+    if (filter.toDate) {
+      conditions.push(`${dateCol} < parseDateTimeBestEffort({var_to_date:String})`);
+      params.var_to_date = filter.toDate.toISOString();
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const countResult = await this.client.query({
+      query: `SELECT count() as count FROM ${TABLE_BACKGROUND_TASKS} FINAL ${where}`,
+      query_params: params,
+      format: "JSONEachRow",
+      clickhouse_settings: { date_time_input_format: "best_effort" }
+    });
+    const countRows = await countResult.json();
+    const total = Number(countRows[0]?.count ?? 0);
+    const orderCol = filter.orderBy === "startedAt" ? "startedAt" : filter.orderBy === "completedAt" ? "completedAt" : "createdAt";
+    const direction = filter.orderDirection === "desc" ? "DESC" : "ASC";
+    let sql = `SELECT * FROM ${TABLE_BACKGROUND_TASKS} FINAL ${where} ORDER BY ${orderCol} ${direction}`;
+    if (filter.perPage != null) {
+      sql += ` LIMIT {var_limit:UInt32}`;
+      params.var_limit = filter.perPage;
+      if (filter.page != null) {
+        sql += ` OFFSET {var_offset:UInt32}`;
+        params.var_offset = filter.page * filter.perPage;
+      }
+    }
+    const result = await this.client.query({
+      query: sql,
+      query_params: params,
+      format: "JSONEachRow",
+      clickhouse_settings: { date_time_input_format: "best_effort" }
+    });
+    const tasks = (await result.json()).map(rowToTask);
+    return { tasks, total };
+  }
+  async deleteTask(taskId) {
+    await this.client.query({
+      query: `ALTER TABLE ${TABLE_BACKGROUND_TASKS} DELETE WHERE id = {var_id:String}`,
+      query_params: { var_id: taskId }
+    });
+  }
+  async deleteTasks(filter) {
+    const { tasks } = await this.listTasks(filter);
+    for (const task of tasks) {
+      await this.client.query({
+        query: `ALTER TABLE ${TABLE_BACKGROUND_TASKS} DELETE WHERE id = {var_id:String}`,
+        query_params: { var_id: task.id }
+      });
+    }
+  }
+  async getRunningCount() {
+    const result = await this.client.query({
+      query: `SELECT count() as count FROM ${TABLE_BACKGROUND_TASKS} FINAL WHERE status = 'running'`,
+      format: "JSONEachRow"
+    });
+    const rows = await result.json();
+    return Number(rows[0]?.count ?? 0);
+  }
+  async getRunningCountByAgent(agentId) {
+    const result = await this.client.query({
+      query: `SELECT count() as count FROM ${TABLE_BACKGROUND_TASKS} FINAL WHERE status = 'running' AND agent_id = {var_agent:String}`,
+      query_params: { var_agent: agentId },
+      format: "JSONEachRow"
+    });
+    const rows = await result.json();
+    return Number(rows[0]?.count ?? 0);
+  }
+};
 function serializeMetadata(metadata) {
   if (!metadata || Object.keys(metadata).length === 0) {
     return "{}";
@@ -2231,6 +2428,49 @@ time for large tables. Please ensure you have a backup before proceeding.
       );
     }
   }
+  async getTraceLight(args) {
+    const { traceId } = args;
+    try {
+      const engine = TABLE_ENGINES[TABLE_SPANS] ?? "MergeTree()";
+      const result = await this.client.query({
+        query: `
+          SELECT traceId, spanId, parentSpanId, name,
+            entityType, entityId, entityName,
+            spanType, error, isEvent,
+            startedAt, endedAt, createdAt, updatedAt
+          FROM ${TABLE_SPANS} ${engine.startsWith("ReplacingMergeTree") ? "FINAL" : ""}
+          WHERE traceId = {traceId:String}
+          ORDER BY startedAt ASC
+        `,
+        query_params: { traceId },
+        format: "JSONEachRow",
+        clickhouse_settings: {
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+      const rows = await result.json();
+      if (!rows || rows.length === 0) {
+        return null;
+      }
+      return {
+        traceId,
+        spans: transformRows(rows)
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "GET_TRACE_LIGHT", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { traceId }
+        },
+        error
+      );
+    }
+  }
   async updateSpan(args) {
     const { traceId, spanId, updates } = args;
     try {
@@ -2745,6 +2985,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_METRIC_EVENTS} (
   timestamp          DateTime64(3, 'UTC'),
 
   -- IDs
+  metricId           String,
   traceId            Nullable(String),
   spanId             Nullable(String),
   experimentId       Nullable(String),
@@ -2792,9 +3033,9 @@ CREATE TABLE IF NOT EXISTS ${TABLE_METRIC_EVENTS} (
   metadata           Nullable(String),
   scope              Nullable(String)
 )
-ENGINE = MergeTree
+ENGINE = ReplacingMergeTree
 PARTITION BY toDate(timestamp)
-ORDER BY (name, timestamp)
+ORDER BY (name, timestamp, metricId)
 `;
 var LOG_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS ${TABLE_LOG_EVENTS} (
@@ -2802,6 +3043,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_LOG_EVENTS} (
   timestamp          DateTime64(3, 'UTC'),
 
   -- IDs
+  logId              String,
   traceId            Nullable(String),
   spanId             Nullable(String),
   experimentId       Nullable(String),
@@ -2844,10 +3086,9 @@ CREATE TABLE IF NOT EXISTS ${TABLE_LOG_EVENTS} (
   metadata           Nullable(String),
   scope              Nullable(String)
 )
-ENGINE = MergeTree
+ENGINE = ReplacingMergeTree
 PARTITION BY toDate(timestamp)
-ORDER BY (timestamp, traceId)
-SETTINGS allow_nullable_key = 1
+ORDER BY (timestamp, logId)
 `;
 var SCORE_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS ${TABLE_SCORE_EVENTS} (
@@ -2855,6 +3096,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_SCORE_EVENTS} (
   timestamp          DateTime64(3, 'UTC'),
 
   -- IDs
+  scoreId            String,
   traceId            Nullable(String),
   spanId             Nullable(String),
   experimentId       Nullable(String),
@@ -2904,9 +3146,9 @@ CREATE TABLE IF NOT EXISTS ${TABLE_SCORE_EVENTS} (
   metadata           Nullable(String),
   scope              Nullable(String)
 )
-ENGINE = MergeTree
+ENGINE = ReplacingMergeTree
 PARTITION BY toDate(timestamp)
-ORDER BY (traceId, timestamp)
+ORDER BY (traceId, timestamp, scoreId)
 SETTINGS allow_nullable_key = 1
 `;
 var FEEDBACK_EVENTS_DDL = `
@@ -2915,6 +3157,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_FEEDBACK_EVENTS} (
   timestamp          DateTime64(3, 'UTC'),
 
   -- IDs
+  feedbackId         String,
   traceId            Nullable(String),
   spanId             Nullable(String),
   experimentId       Nullable(String),
@@ -2967,9 +3210,9 @@ CREATE TABLE IF NOT EXISTS ${TABLE_FEEDBACK_EVENTS} (
   metadata           Nullable(String),
   scope              Nullable(String)
 )
-ENGINE = MergeTree
+ENGINE = ReplacingMergeTree
 PARTITION BY toDate(timestamp)
-ORDER BY (traceId, timestamp)
+ORDER BY (traceId, timestamp, feedbackId)
 SETTINGS allow_nullable_key = 1
 `;
 var DISCOVERY_VALUES_DDL = `
@@ -3324,6 +3567,7 @@ function spanRecordToRow(span) {
 }
 function rowToLogRecord(row) {
   return {
+    logId: row.logId,
     timestamp: toDate(row.timestamp),
     level: row.level,
     message: row.message,
@@ -3360,6 +3604,7 @@ function rowToLogRecord(row) {
 }
 function logRecordToRow(log) {
   return {
+    logId: log.logId,
     timestamp: toISOString(log.timestamp),
     level: log.level,
     message: log.message,
@@ -3396,6 +3641,7 @@ function logRecordToRow(log) {
 }
 function rowToMetricRecord(row) {
   return {
+    metricId: row.metricId,
     timestamp: toDate(row.timestamp),
     name: row.name,
     value: Number(row.value),
@@ -3437,6 +3683,7 @@ function rowToMetricRecord(row) {
 }
 function metricRecordToRow(metric) {
   return {
+    metricId: metric.metricId,
     timestamp: toISOString(metric.timestamp),
     name: metric.name,
     value: metric.value,
@@ -3478,6 +3725,7 @@ function metricRecordToRow(metric) {
 }
 function rowToScoreRecord(row) {
   return {
+    scoreId: row.scoreId,
     timestamp: toDate(row.timestamp),
     // Core score/feedback shapes still type traceId as required for now.
     traceId: nullableString(row.traceId),
@@ -3520,6 +3768,7 @@ function scoreRecordToRow(score) {
   const metadata = score.metadata ?? null;
   const scoreSource = score.scoreSource ?? score.source ?? null;
   return {
+    scoreId: score.scoreId,
     timestamp: toISOString(score.timestamp),
     traceId: score.traceId ?? null,
     spanId: score.spanId ?? null,
@@ -3562,6 +3811,7 @@ function rowToFeedbackRecord(row) {
   const feedbackSource = nullableString(row.feedbackSource);
   const feedbackUserId = nullableString(row.feedbackUserId) ?? nullableString(row.userId);
   return {
+    feedbackId: row.feedbackId,
     timestamp: toDate(row.timestamp),
     // Core score/feedback shapes still type traceId as required for now.
     traceId: nullableString(row.traceId),
@@ -3605,6 +3855,7 @@ function feedbackRecordToRow(feedback) {
   const feedbackSource = feedback.feedbackSource ?? feedback.source ?? "";
   const feedbackUserId = feedback.feedbackUserId ?? feedback.userId ?? null;
   return {
+    feedbackId: feedback.feedbackId,
     timestamp: toISOString(feedback.timestamp),
     traceId: feedback.traceId ?? null,
     spanId: feedback.spanId ?? null,
@@ -4724,6 +4975,93 @@ async function getMetricLabelValues(client, args) {
   );
   return { values: rows.map((r) => r.value) };
 }
+var SIGNAL_MIGRATIONS = [
+  { table: TABLE_METRIC_EVENTS, createDDL: METRIC_EVENTS_DDL, idColumn: "metricId" },
+  { table: TABLE_LOG_EVENTS, createDDL: LOG_EVENTS_DDL, idColumn: "logId" },
+  { table: TABLE_SCORE_EVENTS, createDDL: SCORE_EVENTS_DDL, idColumn: "scoreId" },
+  { table: TABLE_FEEDBACK_EVENTS, createDDL: FEEDBACK_EVENTS_DDL, idColumn: "feedbackId" }
+];
+async function getTableEngine(client, table) {
+  const result = await client.query({
+    query: `SELECT engine FROM system.tables WHERE database = currentDatabase() AND name = {table:String}`,
+    query_params: { table },
+    format: "JSONEachRow"
+  });
+  const rows = await result.json();
+  return rows[0]?.engine ?? null;
+}
+async function getTableColumns(client, table) {
+  const result = await client.query({ query: `DESCRIBE TABLE ${table}`, format: "JSONEachRow" });
+  const rows = await result.json();
+  return rows.map((r) => r.name);
+}
+function buildTemporaryTableDDL(createDDL, table, tempTable) {
+  return createDDL.replace(`CREATE TABLE IF NOT EXISTS ${table}`, `CREATE TABLE ${tempTable}`);
+}
+async function dropTableIfExists(client, table) {
+  if (await getTableEngine(client, table) !== null) {
+    await client.command({ query: `DROP TABLE ${table}` });
+  }
+}
+function createMigrationError(args, error) {
+  return new MastraError(
+    {
+      id: createStorageErrorId("CLICKHOUSE", "MIGRATE_SIGNAL_TABLES", "FAILED"),
+      domain: ErrorDomain.STORAGE,
+      category: ErrorCategory.THIRD_PARTY,
+      details: args
+    },
+    error
+  );
+}
+async function checkSignalTablesMigrationStatus(client) {
+  const tables = [];
+  for (const { table, idColumn } of SIGNAL_MIGRATIONS) {
+    const engine = await getTableEngine(client, table);
+    if (!engine || engine === "ReplacingMergeTree") {
+      continue;
+    }
+    tables.push({ table, engine, idColumn });
+  }
+  return {
+    needsMigration: tables.length > 0,
+    tables
+  };
+}
+async function migrateSignalTables(client, logger) {
+  for (const { table, createDDL, idColumn } of SIGNAL_MIGRATIONS) {
+    const engine = await getTableEngine(client, table);
+    if (!engine || engine === "ReplacingMergeTree") continue;
+    logger?.info?.(`Migrating ${table} from ${engine} to ReplacingMergeTree with ${idColumn} column`);
+    const temp = `${table}_migrating_${Date.now()}`;
+    try {
+      await client.command({ query: buildTemporaryTableDDL(createDDL, table, temp) });
+      const newColumns = await getTableColumns(client, temp);
+      const currentColumns = new Set(await getTableColumns(client, table));
+      const columnList = newColumns.map((c) => `"${c}"`).join(", ");
+      const selectExprs = newColumns.map((c) => {
+        if (c === idColumn) {
+          return currentColumns.has(c) ? `COALESCE(nullIf("${c}", ''), toString(generateUUIDv4())) AS "${c}"` : `toString(generateUUIDv4()) AS "${c}"`;
+        }
+        return currentColumns.has(c) ? `"${c}"` : `NULL AS "${c}"`;
+      }).join(", ");
+      await client.command({
+        query: `INSERT INTO ${temp} (${columnList}) SELECT ${selectExprs} FROM ${table}`
+      });
+      await client.command({ query: `EXCHANGE TABLES ${temp} AND ${table}` });
+      await client.command({ query: `DROP TABLE ${temp}` });
+      logger?.info?.(`Successfully migrated ${table}`);
+    } catch (error) {
+      logger?.error?.(`Migration of ${table} failed: ${error.message}`);
+      try {
+        await dropTableIfExists(client, temp);
+      } catch (restoreError) {
+        logger?.error?.(`Failed to clean up temporary table ${temp}: ${restoreError.message}`);
+      }
+      throw createMigrationError({ table, idColumn }, error);
+    }
+  }
+}
 var SCORE_TYPED_COLUMNS = /* @__PURE__ */ new Set([
   "timestamp",
   "traceId",
@@ -5187,6 +5525,31 @@ async function getTrace(client, args) {
   const spans = rows.map(rowToSpanRecord);
   return { traceId: args.traceId, spans };
 }
+async function getTraceLight(client, args) {
+  const result = await client.query({
+    query: `
+      SELECT traceId, spanId, parentSpanId, name,
+        entityType, entityId, entityName,
+        spanType, error, isEvent,
+        startedAt, endedAt
+      FROM (
+        SELECT *
+        FROM ${TABLE_SPAN_EVENTS}
+        WHERE traceId = {traceId:String}
+        ORDER BY dedupeKey, endedAt DESC
+        LIMIT 1 BY dedupeKey
+      )
+      ORDER BY startedAt ASC
+    `,
+    query_params: { traceId: args.traceId },
+    format: "JSONEachRow",
+    clickhouse_settings: CH_SETTINGS
+  });
+  const rows = await result.json();
+  if (!rows || rows.length === 0) return null;
+  const spans = rows.map(rowToSpanRecord);
+  return { traceId: args.traceId, spans };
+}
 async function batchDeleteTraces(client, args) {
   if (args.traceIds.length === 0) return;
   const params = {};
@@ -5215,6 +5578,32 @@ async function batchDeleteTraces(client, args) {
 }
 
 // src/storage/domains/observability/v-next/index.ts
+function buildSignalMigrationRequiredMessage(args) {
+  const tableList = args.tables.map((table) => `  - ${table.table} (${table.engine})`).join("\n");
+  return `
+===========================================================================
+MIGRATION REQUIRED: ${args.store} observability signal tables need signal IDs
+===========================================================================
+
+The following signal tables still use the legacy schema and must be migrated
+before observability storage can initialize:
+
+${tableList}
+
+To fix this, run the manual migration command:
+
+  npx mastra migrate
+
+This command will:
+  1. Create replacement signal tables with signal-ID dedupe keys
+  2. Backfill missing signal IDs for legacy rows
+  3. Swap the migrated tables into place
+
+WARNING: This migration recreates the signal tables and may take significant
+time for large databases. Please ensure you have a backup before proceeding.
+===========================================================================
+`;
+}
 var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
   #client;
   #retention;
@@ -5228,6 +5617,18 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
   // Initialization
   // -------------------------------------------------------------------------
   async init() {
+    const migrationStatus = await checkSignalTablesMigrationStatus(this.#client);
+    if (migrationStatus.needsMigration) {
+      throw new MastraError({
+        id: createStorageErrorId("CLICKHOUSE", "MIGRATION_REQUIRED", "SIGNAL_TABLES"),
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        text: buildSignalMigrationRequiredMessage({
+          store: "ClickHouse",
+          tables: migrationStatus.tables.map(({ table, engine }) => ({ table, engine }))
+        })
+      });
+    }
     try {
       for (const ddl of [...ALL_TABLE_DDL, ...ALL_MV_DDL]) {
         await this.#client.command({ query: ddl });
@@ -5242,6 +5643,9 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
         }
       }
     } catch (error) {
+      if (error instanceof MastraError) {
+        throw error;
+      }
       throw new MastraError(
         {
           id: createStorageErrorId("CLICKHOUSE", "VNEXT_INIT", "FAILED"),
@@ -5263,6 +5667,29 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
     } catch {
     }
   }
+  /**
+   * Manually migrate legacy signal tables to the signal-ID ReplacingMergeTree schema.
+   * The public method name is historical; the CLI still calls `migrateSpans()`
+   * for observability migrations even though this now also migrates signal tables.
+   */
+  async migrateSpans() {
+    const migrationStatus = await checkSignalTablesMigrationStatus(this.#client);
+    if (!migrationStatus.needsMigration) {
+      return {
+        success: true,
+        alreadyMigrated: true,
+        duplicatesRemoved: 0,
+        message: "Migration already complete. Signal tables already use signal-ID dedupe keys."
+      };
+    }
+    await migrateSignalTables(this.#client, this.logger);
+    return {
+      success: true,
+      alreadyMigrated: false,
+      duplicatesRemoved: 0,
+      message: `Migration complete. Migrated signal tables: ${migrationStatus.tables.map((t) => t.table).join(", ")}.`
+    };
+  }
   // -------------------------------------------------------------------------
   // Strategy
   // -------------------------------------------------------------------------
@@ -5358,6 +5785,22 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
       );
     }
   }
+  async getTraceLight(args) {
+    try {
+      return await getTraceLight(this.#client, args);
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "GET_TRACE_LIGHT", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { traceId: args.traceId }
+        },
+        error
+      );
+    }
+  }
   async listTraces(args) {
     try {
       return await listTraces(this.#client, args);
@@ -6646,7 +7089,8 @@ var ClickhouseStore = class extends MastraCompositeStore {
       workflows,
       scores,
       memory,
-      observability
+      observability,
+      backgroundTasks: new BackgroundTasksStorageClickhouse(domainConfig)
     };
   }
   async optimizeTable({ tableName }) {
@@ -6705,6 +7149,6 @@ var ClickhouseStore = class extends MastraCompositeStore {
   }
 };
 
-export { COLUMN_TYPES, ClickhouseStore, MemoryStorageClickhouse, ObservabilityStorageClickhouse, ObservabilityStorageClickhouseVNext, ScoresStorageClickhouse, TABLE_ENGINES, WorkflowsStorageClickhouse };
+export { BackgroundTasksStorageClickhouse, COLUMN_TYPES, ClickhouseStore, MemoryStorageClickhouse, ObservabilityStorageClickhouse, ObservabilityStorageClickhouseVNext, ScoresStorageClickhouse, TABLE_ENGINES, WorkflowsStorageClickhouse };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map