@mastra/libsql 1.14.3 → 1.15.0-alpha.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createClient } from '@libsql/client';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { createVectorErrorId, AgentsStorage, AGENTS_SCHEMA, TABLE_AGENTS, AGENT_VERSIONS_SCHEMA, TABLE_AGENT_VERSIONS, createStorageErrorId, normalizePerPage, calculatePagination, BackgroundTasksStorage, TABLE_SCHEMAS, TABLE_BACKGROUND_TASKS, BlobStore, TABLE_SKILL_BLOBS, SKILL_BLOBS_SCHEMA, ChannelsStorage, TABLE_CHANNEL_INSTALLATIONS, TABLE_CHANNEL_CONFIG, DatasetsStorage, DATASETS_SCHEMA, TABLE_DATASETS, DATASET_ITEMS_SCHEMA, TABLE_DATASET_ITEMS, DATASET_VERSIONS_SCHEMA, TABLE_DATASET_VERSIONS, ensureDate, safelyParseJSON, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, ExperimentsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, FavoritesStorage, FAVORITES_SCHEMA, TABLE_FAVORITES, TABLE_SKILLS, HarnessStorage, TABLE_HARNESS_SESSIONS, MCPClientsStorage, MCP_CLIENTS_SCHEMA, TABLE_MCP_CLIENTS, MCP_CLIENT_VERSIONS_SCHEMA, TABLE_MCP_CLIENT_VERSIONS, MCPServersStorage, MCP_SERVERS_SCHEMA, TABLE_MCP_SERVERS, MCP_SERVER_VERSIONS_SCHEMA, TABLE_MCP_SERVER_VERSIONS, MemoryStorage, TABLE_THREADS, TABLE_MESSAGES, TABLE_RESOURCES, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, NotificationsStorage, TABLE_NOTIFICATIONS, ObservabilityStorage, SPAN_SCHEMA, TABLE_SPANS, listTracesArgsSchema, toTraceSpans, PromptBlocksStorage, PROMPT_BLOCKS_SCHEMA, TABLE_PROMPT_BLOCKS, PROMPT_BLOCK_VERSIONS_SCHEMA, TABLE_PROMPT_BLOCK_VERSIONS, SchedulesStorage, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, ScorerDefinitionsStorage, SCORER_DEFINITIONS_SCHEMA, TABLE_SCORER_DEFINITIONS, SCORER_DEFINITION_VERSIONS_SCHEMA, TABLE_SCORER_DEFINITION_VERSIONS, ScoresStorage, SCORERS_SCHEMA, TABLE_SCORERS, transformScoreRow, SkillsStorage, SKILLS_SCHEMA, SKILL_VERSIONS_SCHEMA, TABLE_SKILL_VERSIONS, ThreadStateStorage, THREAD_STATE_SCHEMA, TABLE_THREAD_STATE, ToolProviderConnectionsStorage, TOOL_PROVIDER_CONNECTIONS_SCHEMA, TABLE_TOOL_PROVIDER_CONNECTIONS, WorkflowsStorage, TABLE_WORKFLOW_SNAPSHOT, WorkspacesStorage, WORKSPACES_SCHEMA, TABLE_WORKSPACES, WORKSPACE_VERSIONS_SCHEMA, TABLE_WORKSPACE_VERSIONS, MastraCompositeStore, getSqlType, TraceStatus, mergeWorkflowStepResult } from '@mastra/core/storage';
+import { createVectorErrorId, AgentsStorage, AGENTS_SCHEMA, TABLE_AGENTS, AGENT_VERSIONS_SCHEMA, TABLE_AGENT_VERSIONS, createStorageErrorId, normalizePerPage, calculatePagination, BackgroundTasksStorage, TABLE_BACKGROUND_TASKS, TABLE_SCHEMAS, BlobStore, TABLE_SKILL_BLOBS, SKILL_BLOBS_SCHEMA, ChannelsStorage, TABLE_CHANNEL_INSTALLATIONS, TABLE_CHANNEL_CONFIG, DatasetsStorage, DATASETS_SCHEMA, TABLE_DATASETS, DATASET_ITEMS_SCHEMA, TABLE_DATASET_ITEMS, DATASET_VERSIONS_SCHEMA, TABLE_DATASET_VERSIONS, ensureDate, safelyParseJSON, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, ExperimentsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, FavoritesStorage, FAVORITES_SCHEMA, TABLE_FAVORITES, TABLE_SKILLS, HarnessStorage, TABLE_HARNESS_SESSIONS, MCPClientsStorage, MCP_CLIENTS_SCHEMA, TABLE_MCP_CLIENTS, MCP_CLIENT_VERSIONS_SCHEMA, TABLE_MCP_CLIENT_VERSIONS, MCPServersStorage, MCP_SERVERS_SCHEMA, TABLE_MCP_SERVERS, MCP_SERVER_VERSIONS_SCHEMA, TABLE_MCP_SERVER_VERSIONS, MemoryStorage, TABLE_THREADS, TABLE_RESOURCES, TABLE_MESSAGES, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, NotificationsStorage, TABLE_NOTIFICATIONS, ObservabilityStorage, TABLE_SPANS, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, PromptBlocksStorage, PROMPT_BLOCKS_SCHEMA, TABLE_PROMPT_BLOCKS, PROMPT_BLOCK_VERSIONS_SCHEMA, TABLE_PROMPT_BLOCK_VERSIONS, SchedulesStorage, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEDULES, ScorerDefinitionsStorage, SCORER_DEFINITIONS_SCHEMA, TABLE_SCORER_DEFINITIONS, SCORER_DEFINITION_VERSIONS_SCHEMA, TABLE_SCORER_DEFINITION_VERSIONS, ScoresStorage, TABLE_SCORERS, SCORERS_SCHEMA, transformScoreRow, SkillsStorage, SKILLS_SCHEMA, SKILL_VERSIONS_SCHEMA, TABLE_SKILL_VERSIONS, ThreadStateStorage, TABLE_THREAD_STATE, THREAD_STATE_SCHEMA, ToolProviderConnectionsStorage, TOOL_PROVIDER_CONNECTIONS_SCHEMA, TABLE_TOOL_PROVIDER_CONNECTIONS, WorkflowsStorage, TABLE_WORKFLOW_SNAPSHOT, WorkspacesStorage, WORKSPACES_SCHEMA, TABLE_WORKSPACES, WORKSPACE_VERSIONS_SCHEMA, TABLE_WORKSPACE_VERSIONS, MastraCompositeStore, getSqlType, parseDuration, TraceStatus, mergeWorkflowStepResult } from '@mastra/core/storage';
 import { parseSqlIdentifier, parseFieldKey } from '@mastra/core/utils';
 import { MastraVector, validateTopK, validateUpsertInput } from '@mastra/core/vector';
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
@@ -1456,6 +1456,11 @@ function resolveClient(config) {
     ...isLocal ? { timeout } : {}
   });
 }
+function assertPositiveLimit(limit) {
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new Error(`prune limit must be a positive integer; received ${limit}`);
+  }
+}
 var LibSQLDB = class extends MastraBase {
   client;
   maxRetries;
@@ -2276,6 +2281,102 @@ Note: This migration may take some time for large tables.
       this.logger?.error?.(mastraError.toString());
     }
   }
+  // ---------------------------------------------------------------------------
+  // Retention helpers (prune)
+  //
+  // Low-level SQL primitives the memory and observability domains build their
+  // `prune()` on, plus a plain user-invoked `VACUUM`. Keeping the SQL here
+  // reuses the existing write-lock + retry machinery and keeps identifier
+  // parsing in one place.
+  // ---------------------------------------------------------------------------
+  /**
+   * Delete up to `limit` of the oldest rows whose `column` timestamp is strictly
+   * before `cutoffMs`, in a single bounded statement. Returns the number of rows
+   * removed so the caller can decide whether more batches remain.
+   *
+   * Deletes by `rowid` so the range scan is bounded by LIMIT and the write set
+   * stays small — short locks, bounded WAL growth. Requires an index on
+   * `column` to be fast at scale (see ensureIndex).
+   */
+  async pruneBatch({
+    tableName,
+    column,
+    cutoff,
+    limit
+  }) {
+    assertPositiveLimit(limit);
+    const parsedTable = parseSqlIdentifier(tableName, "table name");
+    const parsedColumn = parseSqlIdentifier(column, "column name");
+    const sql = `DELETE FROM "${parsedTable}" WHERE rowid IN (SELECT rowid FROM "${parsedTable}" WHERE "${parsedColumn}" < ? LIMIT ?)`;
+    const result = await this.executeWriteOperationWithRetry(
+      () => withClientWriteLock(this.client, () => this.client.execute({ sql, args: [cutoff, limit] })),
+      `prune ${tableName}`
+    );
+    return Number(result.rowsAffected ?? 0);
+  }
+  /**
+   * Delete up to `limit` aged parent rows *and* their child rows together, in a
+   * single transaction. Used for whole-unit (parent-driven) pruning where
+   * children must die with their parent (e.g. an aged experiment and its
+   * experiment_results) — deleting per unit means a bound or abort between
+   * batches never leaves a parent hollow (kept, but with its children gone) or
+   * children orphaned.
+   *
+   * Both deletes target the same parent set via an identical deterministic
+   * subquery (`ORDER BY rowid LIMIT ?`); the batch runs as one write
+   * transaction, so the set cannot change between the two statements.
+   */
+  async pruneUnitsBatch({
+    parentTable,
+    parentKey,
+    parentColumn,
+    childTable,
+    childForeignKey,
+    cutoff,
+    limit
+  }) {
+    assertPositiveLimit(limit);
+    const parsedChild = parseSqlIdentifier(childTable, "table name");
+    const parsedChildFk = parseSqlIdentifier(childForeignKey, "column name");
+    const parsedParent = parseSqlIdentifier(parentTable, "table name");
+    const parsedParentKey = parseSqlIdentifier(parentKey, "column name");
+    const parsedParentColumn = parseSqlIdentifier(parentColumn, "column name");
+    const agedParents = `SELECT "${parsedParentKey}" FROM "${parsedParent}" WHERE "${parsedParentColumn}" < ? ORDER BY rowid LIMIT ?`;
+    const results = await this.executeWriteOperationWithRetry(
+      () => withClientWriteLock(
+        this.client,
+        () => this.client.batch(
+          [
+            {
+              sql: `DELETE FROM "${parsedChild}" WHERE "${parsedChildFk}" IN (${agedParents})`,
+              args: [cutoff, limit]
+            },
+            {
+              sql: `DELETE FROM "${parsedParent}" WHERE "${parsedParentKey}" IN (${agedParents})`,
+              args: [cutoff, limit]
+            }
+          ],
+          "write"
+        )
+      ),
+      `prune units ${parentTable}`
+    );
+    return {
+      children: Number(results[0]?.rowsAffected ?? 0),
+      parents: Number(results[1]?.rowsAffected ?? 0)
+    };
+  }
+  /** Create an index if it does not already exist. */
+  async ensureIndex({
+    indexName,
+    tableName,
+    column
+  }) {
+    const parsedTable = parseSqlIdentifier(tableName, "table name");
+    const parsedColumn = parseSqlIdentifier(column, "column name");
+    const parsedIndex = parseSqlIdentifier(indexName, "index name");
+    await this.client.execute(`CREATE INDEX IF NOT EXISTS "${parsedIndex}" ON "${parsedTable}" ("${parsedColumn}")`);
+  }
 };
 var AgentsLibSQL = class extends AgentsStorage {
   #db;
@@ -3113,6 +3214,113 @@ var AgentsLibSQL = class extends AgentsStorage {
     };
   }
 };
+var DEFAULT_BATCH_SIZE = 1e3;
+async function ensureAnchorIndex(db, target, logger) {
+  if (!target.indexed) return;
+  try {
+    await db.ensureIndex({
+      indexName: `idx_retention_${target.table}_${target.column}`,
+      tableName: target.table,
+      column: target.column
+    });
+  } catch (error) {
+    logger?.warn?.(`Failed to ensure retention index on ${target.table}(${target.column}):`, error);
+  }
+}
+async function sleep(ms, signal) {
+  if (ms <= 0 || signal?.aborted) return;
+  await new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function cutoffFor(policy, anchorType, now = Date.now()) {
+  const cutoffMs = now - parseDuration(policy.maxAge);
+  return anchorType === "epoch-ms" ? cutoffMs : new Date(cutoffMs).toISOString();
+}
+async function runBatchedDelete({
+  deleteBatch,
+  batchSize,
+  options
+}) {
+  if (!Number.isSafeInteger(batchSize) || batchSize <= 0) {
+    throw new Error(`retention batchSize must be a positive integer; received ${batchSize}`);
+  }
+  let deleted = 0;
+  let batches = 0;
+  while (true) {
+    if (options?.signal?.aborted) return { deleted, done: false };
+    if (options?.maxBatches !== void 0 && batches >= options.maxBatches) return { deleted, done: false };
+    let limit = batchSize;
+    if (options?.maxRows !== void 0) {
+      const remaining = options.maxRows - deleted;
+      if (remaining <= 0) return { deleted, done: false };
+      limit = Math.min(limit, remaining);
+    }
+    const affected = await deleteBatch(limit);
+    deleted += affected;
+    batches += 1;
+    if (affected < limit) return { deleted, done: true };
+    if (options?.pauseMs) {
+      await sleep(options.pauseMs, options.signal);
+    }
+  }
+}
+async function runPrune({
+  db,
+  domain,
+  targets,
+  options,
+  logger
+}) {
+  const results = [];
+  const now = Date.now();
+  for (const target of targets) {
+    if (options?.signal?.aborted) {
+      results.push({ domain, table: target.table, deleted: 0, done: false });
+      continue;
+    }
+    await ensureAnchorIndex(db, target, logger);
+    const cutoff = cutoffFor(target.policy, target.anchorType, now);
+    const batchSize = target.policy.batchSize ?? DEFAULT_BATCH_SIZE;
+    const { deleted, done } = await runBatchedDelete({
+      deleteBatch: (limit) => db.pruneBatch({ tableName: target.table, column: target.column, cutoff, limit }),
+      batchSize,
+      options
+    });
+    results.push({ domain, table: target.table, deleted, done });
+  }
+  return results;
+}
+function resolveTargets({
+  policies,
+  descriptor,
+  order
+}) {
+  const targets = [];
+  for (const key of order) {
+    const policy = policies[key];
+    const entry = descriptor[key];
+    if (!policy || !entry) continue;
+    targets.push({
+      table: entry.table,
+      column: entry.column,
+      anchorType: entry.anchorType ?? "timestamp",
+      indexed: entry.indexed ?? true,
+      policy
+    });
+  }
+  return targets;
+}
+
+// src/storage/domains/background-tasks/index.ts
 function serializeJson(v) {
   if (typeof v === "object" && v != null) return JSON.stringify(v);
   return v ?? null;
@@ -3151,7 +3359,15 @@ function rowToTask(row) {
     completedAt: row.completedAt ? new Date(String(row.completedAt)) : void 0
   };
 }
-var BackgroundTasksLibSQL = class extends BackgroundTasksStorage {
+var BackgroundTasksLibSQL = class _BackgroundTasksLibSQL extends BackgroundTasksStorage {
+  /**
+   * Completed/failed task records accumulate. Anchored on `completedAt`, which
+   * is NULL while a task is in-flight (pending/running/suspended) — so `completedAt
+   * < cutoff` never prunes a live task, no explicit status filter needed.
+   */
+  static retentionTables = {
+    backgroundTasks: { table: TABLE_BACKGROUND_TASKS, column: "completedAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -3174,6 +3390,15 @@ var BackgroundTasksLibSQL = class extends BackgroundTasksStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: TABLE_BACKGROUND_TASKS });
   }
+  /** Delete completed tasks older than the `backgroundTasks` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _BackgroundTasksLibSQL.retentionTables,
+      order: ["backgroundTasks"]
+    });
+    return runPrune({ db: this.#db, domain: "backgroundTasks", targets, options, logger: this.logger });
+  }
   async createTask(task) {
     await this.#db.insert({
       tableName: TABLE_BACKGROUND_TASKS,
@@ -4624,7 +4849,18 @@ var DatasetsLibSQL = class extends DatasetsStorage {
     }
   }
 };
+var DEFAULT_PRUNE_BATCH_SIZE = 1e3;
 var ExperimentsLibSQL = class extends ExperimentsStorage {
+  /**
+   * An experiment is pruned as a whole unit: when `experiments.completedAt` is
+   * older than the policy, the run and all its `experiment_results` rows are
+   * deleted together (results cascade with their parent, matching
+   * `deleteExperiment`). Results are not an independent retention key. NULL
+   * `completedAt` (still running) is never pruned.
+   */
+  static retentionTables = {
+    experiments: { table: TABLE_EXPERIMENTS, column: "completedAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -4680,6 +4916,58 @@ var ExperimentsLibSQL = class extends ExperimentsStorage {
     await this.#db.deleteData({ tableName: TABLE_EXPERIMENT_RESULTS });
     await this.#db.deleteData({ tableName: TABLE_EXPERIMENTS });
   }
+  /**
+   * Prune whole experiments older than the `experiments` policy's `maxAge`.
+   *
+   * Each batch selects up to `batchSize` aged experiments and deletes their
+   * `experiment_results` rows and the experiment rows in one transaction —
+   * mirroring `deleteExperiment` — so hitting `maxBatches`/`maxRows` or the
+   * abort signal between batches never leaves a run hollow (parent kept,
+   * results gone). NULL `completedAt` (still running) is excluded by the
+   * `< cutoff` predicate. Bounds count whole experiments, not rows.
+   */
+  async prune(policies, options) {
+    const policy = policies["experiments"];
+    if (!policy || options?.signal?.aborted) {
+      return policy ? [
+        { domain: "experiments", table: TABLE_EXPERIMENT_RESULTS, deleted: 0, done: false },
+        { domain: "experiments", table: TABLE_EXPERIMENTS, deleted: 0, done: false }
+      ] : [];
+    }
+    try {
+      await this.#db.ensureIndex({
+        indexName: `idx_retention_${TABLE_EXPERIMENTS}_completedAt`,
+        tableName: TABLE_EXPERIMENTS,
+        column: "completedAt"
+      });
+    } catch (error) {
+      this.logger?.warn?.(`Failed to ensure retention index on ${TABLE_EXPERIMENTS}(completedAt):`, error);
+    }
+    const cutoff = cutoffFor(policy, "timestamp");
+    const batchSize = policy.batchSize ?? DEFAULT_PRUNE_BATCH_SIZE;
+    let childDeleted = 0;
+    const parent = await runBatchedDelete({
+      deleteBatch: async (limit) => {
+        const { parents, children } = await this.#db.pruneUnitsBatch({
+          parentTable: TABLE_EXPERIMENTS,
+          parentKey: "id",
+          parentColumn: "completedAt",
+          childTable: TABLE_EXPERIMENT_RESULTS,
+          childForeignKey: "experimentId",
+          cutoff,
+          limit
+        });
+        childDeleted += children;
+        return parents;
+      },
+      batchSize,
+      options
+    });
+    return [
+      { domain: "experiments", table: TABLE_EXPERIMENT_RESULTS, deleted: childDeleted, done: parent.done },
+      { domain: "experiments", table: TABLE_EXPERIMENTS, deleted: parent.deleted, done: parent.done }
+    ];
+  }
   // Helper to transform row to Experiment
   transformExperimentRow(row) {
     return {
@@ -5567,7 +5855,11 @@ function sessionToRecord(record) {
     deletedAt: record.deletedAt ?? null
   };
 }
-var HarnessLibSQL = class extends HarnessStorage {
+var HarnessLibSQL = class _HarnessLibSQL extends HarnessStorage {
+  /** Session records accumulate over time. Single table, anchored on `createdAt`. */
+  static retentionTables = {
+    sessions: { table: TABLE_HARNESS_SESSIONS, column: "createdAt", indexed: true }
+  };
   #db;
   constructor(config) {
     super();
@@ -5583,6 +5875,15 @@ var HarnessLibSQL = class extends HarnessStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: TABLE_HARNESS_SESSIONS });
   }
+  /** Delete harness sessions older than the `sessions` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _HarnessLibSQL.retentionTables,
+      order: ["sessions"]
+    });
+    return runPrune({ db: this.#db, domain: "harness", targets, options, logger: this.logger });
+  }
   async loadSession(sessionId) {
     const row = await this.#db.select({
       tableName: TABLE_HARNESS_SESSIONS,
@@ -6568,8 +6869,18 @@ var MCPServersLibSQL = class extends MCPServersStorage {
   }
 };
 var OM_TABLE = "mastra_observational_memory";
-var MemoryLibSQL = class extends MemoryStorage {
+var MemoryLibSQL = class _MemoryLibSQL extends MemoryStorage {
   supportsObservationalMemory = true;
+  /**
+   * Retention-eligible tables. `threads`, `messages`, and `resources` all anchor
+   * on `createdAt` and are indexed for fast batched deletes. Cascade order is
+   * enforced in `prune()` (children before threads), not here.
+   */
+  static retentionTables = {
+    messages: { table: TABLE_MESSAGES, column: "createdAt", indexed: true },
+    resources: { table: TABLE_RESOURCES, column: "createdAt", indexed: true },
+    threads: { table: TABLE_THREADS, column: "createdAt", indexed: true }
+  };
   #client;
   #db;
   constructor(config) {
@@ -6644,6 +6955,21 @@ var MemoryLibSQL = class extends MemoryStorage {
       await this.#db.deleteData({ tableName: OM_TABLE });
     }
   }
+  /**
+   * Delete rows older than each policy's `maxAge`, batched and cancellable.
+   *
+   * Deletes children before parents (messages/resources before threads) so a
+   * `threads` policy doesn't strand rows behind a deleted parent — there are no
+   * FKs in the LibSQL schema, so cascade ordering is explicit here.
+   */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _MemoryLibSQL.retentionTables,
+      order: ["messages", "resources", "threads"]
+    });
+    return runPrune({ db: this.#db, domain: "memory", targets, options, logger: this.logger });
+  }
   parseRow(row) {
     let content = row.content;
     try {
@@ -8710,7 +9036,11 @@ function addArrayFilter(conditions, args, column, value) {
   conditions.push(`"${column}" IN (${values.map(() => "?").join(", ")})`);
   args.push(...values);
 }
-var NotificationsLibSQL = class extends NotificationsStorage {
+var NotificationsLibSQL = class _NotificationsLibSQL extends NotificationsStorage {
+  /** The notification feed grows unbounded. Single table, anchored on `createdAt`. */
+  static retentionTables = {
+    notifications: { table: TABLE_NOTIFICATIONS, column: "createdAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -8745,6 +9075,15 @@ var NotificationsLibSQL = class extends NotificationsStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: TABLE_NOTIFICATIONS });
   }
+  /** Delete notifications older than the `notifications` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _NotificationsLibSQL.retentionTables,
+      order: ["notifications"]
+    });
+    return runPrune({ db: this.#db, domain: "notifications", targets, options, logger: this.logger });
+  }
   async createNotification(input) {
     const existing = await this.findCoalescable(input);
     if (existing) {
@@ -8934,7 +9273,14 @@ var NotificationsLibSQL = class extends NotificationsStorage {
     return row ? rowToNotification(row) : void 0;
   }
 };
-var ObservabilityLibSQL = class extends ObservabilityStorage {
+var ObservabilityLibSQL = class _ObservabilityLibSQL extends ObservabilityStorage {
+  /**
+   * Spans are the only physical table; traces are derived from them. Spans
+   * anchor on `startedAt` (not `createdAt`), stored as an ISO-8601 string.
+   */
+  static retentionTables = {
+    spans: { table: TABLE_SPANS, column: "startedAt", indexed: true }
+  };
   #db;
   constructor(config) {
     super();
@@ -8952,6 +9298,15 @@ var ObservabilityLibSQL = class extends ObservabilityStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: TABLE_SPANS });
   }
+  /** Delete spans older than the `spans` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _ObservabilityLibSQL.retentionTables,
+      order: ["spans"]
+    });
+    return runPrune({ db: this.#db, domain: "observability", targets, options, logger: this.logger });
+  }
   /**
    * Manually run the spans migration to deduplicate and add the unique constraint.
    * This is intended to be called from the CLI when duplicates are detected.
@@ -9960,7 +10315,15 @@ function rowToTrigger(row) {
   if (metadata !== void 0) trigger.metadata = metadata;
   return trigger;
 }
-var SchedulesLibSQL = class extends SchedulesStorage {
+var SchedulesLibSQL = class _SchedulesLibSQL extends SchedulesStorage {
+  /**
+   * The fire/run history (`schedule_triggers`, one row per fire) is the growth
+   * table; schedule definitions are config and excluded. Anchored on
+   * `actual_fire_at`, a bigint epoch-ms column (numeric comparison, not ISO).
+   */
+  static retentionTables = {
+    triggers: { table: TABLE_SCHEDULE_TRIGGERS, column: "actual_fire_at", indexed: true, anchorType: "epoch-ms" }
+  };
   #db;
   #client;
   constructor(config) {
@@ -9996,6 +10359,15 @@ var SchedulesLibSQL = class extends SchedulesStorage {
     await this.#db.deleteData({ tableName: TABLE_SCHEDULE_TRIGGERS });
     await this.#db.deleteData({ tableName: TABLE_SCHEDULES });
   }
+  /** Delete schedule fire history older than the `triggers` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _SchedulesLibSQL.retentionTables,
+      order: ["triggers"]
+    });
+    return runPrune({ db: this.#db, domain: "schedules", targets, options, logger: this.logger });
+  }
   async createSchedule(schedule) {
     const existing = await this.getSchedule(schedule.id);
     if (existing) {
@@ -10670,7 +11042,13 @@ var ScorerDefinitionsLibSQL = class extends ScorerDefinitionsStorage {
     };
   }
 };
-var ScoresLibSQL = class extends ScoresStorage {
+var ScoresLibSQL = class _ScoresLibSQL extends ScoresStorage {
+  /**
+   * Scorer results accumulate as evals run. Single table, anchored on `createdAt`.
+   */
+  static retentionTables = {
+    scorers: { table: TABLE_SCORERS, column: "createdAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -10690,6 +11068,15 @@ var ScoresLibSQL = class extends ScoresStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: TABLE_SCORERS });
   }
+  /** Delete scorer results older than the `scorers` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _ScoresLibSQL.retentionTables,
+      order: ["scorers"]
+    });
+    return runPrune({ db: this.#db, domain: "scores", targets, options, logger: this.logger });
+  }
   async listScoresByRunId({
     runId,
     pagination
@@ -11573,7 +11960,15 @@ var SkillsLibSQL = class extends SkillsStorage {
     };
   }
 };
-var ThreadStateLibSQL = class extends ThreadStateStorage {
+var ThreadStateLibSQL = class _ThreadStateLibSQL extends ThreadStateStorage {
+  /**
+   * `thread_state` grows as a side effect of thread activity (one row per
+   * thread per state type). It anchors on `updatedAt` (last activity), so state
+   * for a thread that is still being appended to is not pruned by creation age.
+   */
+  static retentionTables = {
+    threadState: { table: TABLE_THREAD_STATE, column: "updatedAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -11589,6 +11984,15 @@ var ThreadStateLibSQL = class extends ThreadStateStorage {
       compositePrimaryKey: ["threadId", "type"]
     });
   }
+  /** Delete thread state older than the `threadState` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _ThreadStateLibSQL.retentionTables,
+      order: ["threadState"]
+    });
+    return runPrune({ db: this.#db, domain: "threadState", targets, options, logger: this.logger });
+  }
   async dangerouslyClearAll() {
     try {
       await this.#client.execute(`DELETE FROM "${TABLE_THREAD_STATE}"`);
@@ -11857,7 +12261,14 @@ var ToolProviderConnectionsLibSQL = class extends ToolProviderConnectionsStorage
     }
   }
 };
-var WorkflowsLibSQL = class extends WorkflowsStorage {
+var WorkflowsLibSQL = class _WorkflowsLibSQL extends WorkflowsStorage {
+  /**
+   * Workflow run snapshots accumulate as runs execute. Anchored on `updatedAt`
+   * (last activity) so suspended/long-running runs are not pruned by start age.
+   */
+  static retentionTables = {
+    workflowSnapshot: { table: TABLE_WORKFLOW_SNAPSHOT, column: "updatedAt", indexed: true }
+  };
   #db;
   #client;
   executeWithRetry;
@@ -11910,6 +12321,15 @@ var WorkflowsLibSQL = class extends WorkflowsStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: TABLE_WORKFLOW_SNAPSHOT });
   }
+  /** Delete workflow snapshots older than the `workflowSnapshot` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    const targets = resolveTargets({
+      policies,
+      descriptor: _WorkflowsLibSQL.retentionTables,
+      order: ["workflowSnapshot"]
+    });
+    return runPrune({ db: this.#db, domain: "workflows", targets, options, logger: this.logger });
+  }
   async setupPragmaSettings() {
     try {
       await this.#client.execute("PRAGMA busy_timeout = 10000;");
@@ -12765,7 +13185,7 @@ var LibSQLStore = class extends MastraCompositeStore {
     if (!config.id || typeof config.id !== "string" || config.id.trim() === "") {
       throw new Error("LibSQLStore: id must be provided and cannot be empty.");
     }
-    super({ id: config.id, name: `LibSQLStore`, disableInit: config.disableInit });
+    super({ id: config.id, name: `LibSQLStore`, disableInit: config.disableInit, retention: config.retention });
     this.maxRetries = config.maxRetries ?? 5;
     this.initialBackoffMs = config.initialBackoffMs ?? 100;
     this.connectionTimeoutMs = config.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS;