@mastra/libsql 1.14.3 → 1.15.0-alpha.1

package/dist/index.cjs

@@ -1458,6 +1458,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 base.MastraBase {
   client;
   maxRetries;
@@ -2278,6 +2283,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 = utils.parseSqlIdentifier(tableName, "table name");
+    const parsedColumn = utils.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 = utils.parseSqlIdentifier(childTable, "table name");
+    const parsedChildFk = utils.parseSqlIdentifier(childForeignKey, "column name");
+    const parsedParent = utils.parseSqlIdentifier(parentTable, "table name");
+    const parsedParentKey = utils.parseSqlIdentifier(parentKey, "column name");
+    const parsedParentColumn = utils.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 = utils.parseSqlIdentifier(tableName, "table name");
+    const parsedColumn = utils.parseSqlIdentifier(column, "column name");
+    const parsedIndex = utils.parseSqlIdentifier(indexName, "index name");
+    await this.client.execute(`CREATE INDEX IF NOT EXISTS "${parsedIndex}" ON "${parsedTable}" ("${parsedColumn}")`);
+  }
 };
 var AgentsLibSQL = class extends storage.AgentsStorage {
   #db;
@@ -3115,6 +3216,113 @@ var AgentsLibSQL = class extends storage.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 - storage.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;
@@ -3153,7 +3361,15 @@ function rowToTask(row) {
     completedAt: row.completedAt ? new Date(String(row.completedAt)) : void 0
   };
 }
-var BackgroundTasksLibSQL = class extends storage.BackgroundTasksStorage {
+var BackgroundTasksLibSQL = class _BackgroundTasksLibSQL extends storage.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: storage.TABLE_BACKGROUND_TASKS, column: "completedAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -3176,6 +3392,15 @@ var BackgroundTasksLibSQL = class extends storage.BackgroundTasksStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.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: storage.TABLE_BACKGROUND_TASKS,
@@ -3601,6 +3826,30 @@ var ChannelsLibSQL = class extends storage.ChannelsStorage {
     };
   }
 };
+
+// src/storage/domains/utils.ts
+function tenancyWhere(filters) {
+  const conditions = [];
+  const params = [];
+  if (filters?.organizationId !== void 0) {
+    conditions.push("organizationId = ?");
+    params.push(filters.organizationId);
+  }
+  if (filters?.projectId !== void 0) {
+    conditions.push("projectId = ?");
+    params.push(filters.projectId);
+  }
+  return { conditions, params };
+}
+function buildScopedWhere(idColumn, idValue, filters) {
+  const { conditions, params } = tenancyWhere(filters);
+  return {
+    sql: [`${idColumn} = ?`, ...conditions].join(" AND "),
+    args: [idValue, ...params]
+  };
+}
+
+// src/storage/domains/datasets/index.ts
 function jsonbArg(value) {
   return value === void 0 || value === null ? null : JSON.stringify(value);
 }
@@ -3681,6 +3930,18 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
     await this.#db.deleteData({ tableName: storage.TABLE_DATASET_ITEMS });
     await this.#db.deleteData({ tableName: storage.TABLE_DATASETS });
   }
+  async experimentTablesExist() {
+    try {
+      const result = await this.#client.execute({
+        sql: `SELECT COUNT(*) AS c FROM sqlite_master WHERE type = 'table' AND name IN (?, ?)`,
+        args: [storage.TABLE_EXPERIMENTS, storage.TABLE_EXPERIMENT_RESULTS]
+      });
+      const row = result.rows?.[0];
+      return Number(row?.c ?? 0) === 2;
+    } catch {
+      return false;
+    }
+  }
   // --- Row transformers ---
   transformDatasetRow(row) {
     return {
@@ -3767,8 +4028,8 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
           groundTruthSchema: input.groundTruthSchema ?? null,
           requestContextSchema: input.requestContextSchema ?? null,
           targetType: input.targetType ?? null,
-          targetIds: input.targetIds ? JSON.stringify(input.targetIds) : null,
-          scorerIds: input.scorerIds ? JSON.stringify(input.scorerIds) : null,
+          targetIds: input.targetIds ?? null,
+          scorerIds: input.scorerIds ?? null,
           version: 0,
           organizationId: input.organizationId ?? null,
           projectId: input.projectId ?? null,
@@ -3808,11 +4069,16 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
       );
     }
   }
-  async getDatasetById({ id }) {
+  async getDatasetById({
+    id,
+    filters
+  }) {
     try {
+      const { conditions, params } = tenancyWhere(filters);
+      const whereSql = ["id = ?", ...conditions].join(" AND ");
       const result = await this.#client.execute({
-        sql: `SELECT ${buildSelectColumns(storage.TABLE_DATASETS)} FROM ${storage.TABLE_DATASETS} WHERE id = ?`,
-        args: [id]
+        sql: `SELECT ${buildSelectColumns(storage.TABLE_DATASETS)} FROM ${storage.TABLE_DATASETS} WHERE ${whereSql}`,
+        args: [id, ...params]
       });
       return result.rows?.[0] ? this.transformDatasetRow(result.rows[0]) : null;
     } catch (error$1) {
@@ -3828,7 +4094,7 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
   }
   async _doUpdateDataset(args) {
     try {
-      const existing = await this.getDatasetById({ id: args.id });
+      const existing = await this.getDatasetById({ id: args.id, filters: args.filters });
       if (!existing) {
         throw new error.MastraError({
           id: storage.createStorageErrorId("LIBSQL", "UPDATE_DATASET", "NOT_FOUND"),
@@ -3911,30 +4177,31 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
       );
     }
   }
-  async deleteDataset({ id }) {
+  async deleteDataset({ id, filters }) {
     try {
-      try {
-        await this.#client.execute({
+      const { conditions, params } = tenancyWhere(filters);
+      const scopedWhere = ["id = ?", ...conditions].join(" AND ");
+      const exists = await this.#client.execute({
+        sql: `SELECT id FROM ${storage.TABLE_DATASETS} WHERE ${scopedWhere}`,
+        args: [id, ...params]
+      });
+      if (!exists.rows?.[0]) return;
+      const experimentTablesExist = await this.experimentTablesExist();
+      const statements = [];
+      if (experimentTablesExist) {
+        statements.push({
           sql: `DELETE FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE experimentId IN (SELECT id FROM ${storage.TABLE_EXPERIMENTS} WHERE datasetId = ?)`,
           args: [id]
         });
-      } catch {
-      }
-      try {
-        await this.#client.execute({
+        statements.push({
           sql: `UPDATE ${storage.TABLE_EXPERIMENTS} SET datasetId = NULL, datasetVersion = NULL WHERE datasetId = ?`,
           args: [id]
         });
-      } catch {
       }
-      await this.#client.batch(
-        [
-          { sql: `DELETE FROM ${storage.TABLE_DATASET_VERSIONS} WHERE datasetId = ?`, args: [id] },
-          { sql: `DELETE FROM ${storage.TABLE_DATASET_ITEMS} WHERE datasetId = ?`, args: [id] },
-          { sql: `DELETE FROM ${storage.TABLE_DATASETS} WHERE id = ?`, args: [id] }
-        ],
-        "write"
-      );
+      statements.push({ sql: `DELETE FROM ${storage.TABLE_DATASET_VERSIONS} WHERE datasetId = ?`, args: [id] });
+      statements.push({ sql: `DELETE FROM ${storage.TABLE_DATASET_ITEMS} WHERE datasetId = ?`, args: [id] });
+      statements.push({ sql: `DELETE FROM ${storage.TABLE_DATASETS} WHERE ${scopedWhere}`, args: [id, ...params] });
+      await this.#client.batch(statements, "write");
     } catch (error$1) {
       throw new error.MastraError(
         {
@@ -3967,6 +4234,21 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
         filterConditions.push("candidateId = ?");
         filterParams.push(args.filters.candidateId);
       }
+      if (args.filters?.targetType !== void 0) {
+        filterConditions.push("targetType = ?");
+        filterParams.push(args.filters.targetType);
+      }
+      if (args.filters?.targetIds !== void 0 && args.filters.targetIds.length > 0) {
+        const placeholders = args.filters.targetIds.map(() => "?").join(",");
+        filterConditions.push(
+          `EXISTS (SELECT 1 FROM json_each(${storage.TABLE_DATASETS}.targetIds) WHERE value IN (${placeholders}))`
+        );
+        for (const id of args.filters.targetIds) filterParams.push(id);
+      }
+      if (args.filters?.name !== void 0 && args.filters.name.length > 0) {
+        filterConditions.push("LOWER(name) LIKE ?");
+        filterParams.push(`%${args.filters.name.toLowerCase()}%`);
+      }
       const whereClause = filterConditions.length > 0 ? `WHERE ${filterConditions.join(" AND ")}` : "";
       const countResult = await this.#client.execute({
         sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_DATASETS} ${whereClause}`,
@@ -4626,7 +4908,18 @@ var DatasetsLibSQL = class extends storage.DatasetsStorage {
     }
   }
 };
+var DEFAULT_PRUNE_BATCH_SIZE = 1e3;
 var ExperimentsLibSQL = class extends storage.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: storage.TABLE_EXPERIMENTS, column: "completedAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -4682,6 +4975,58 @@ var ExperimentsLibSQL = class extends storage.ExperimentsStorage {
     await this.#db.deleteData({ tableName: storage.TABLE_EXPERIMENT_RESULTS });
     await this.#db.deleteData({ tableName: storage.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: storage.TABLE_EXPERIMENT_RESULTS, deleted: 0, done: false },
+        { domain: "experiments", table: storage.TABLE_EXPERIMENTS, deleted: 0, done: false }
+      ] : [];
+    }
+    try {
+      await this.#db.ensureIndex({
+        indexName: `idx_retention_${storage.TABLE_EXPERIMENTS}_completedAt`,
+        tableName: storage.TABLE_EXPERIMENTS,
+        column: "completedAt"
+      });
+    } catch (error) {
+      this.logger?.warn?.(`Failed to ensure retention index on ${storage.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: storage.TABLE_EXPERIMENTS,
+          parentKey: "id",
+          parentColumn: "completedAt",
+          childTable: storage.TABLE_EXPERIMENT_RESULTS,
+          childForeignKey: "experimentId",
+          cutoff,
+          limit
+        });
+        childDeleted += children;
+        return parents;
+      },
+      batchSize,
+      options
+    });
+    return [
+      { domain: "experiments", table: storage.TABLE_EXPERIMENT_RESULTS, deleted: childDeleted, done: parent.done },
+      { domain: "experiments", table: storage.TABLE_EXPERIMENTS, deleted: parent.deleted, done: parent.done }
+    ];
+  }
   // Helper to transform row to Experiment
   transformExperimentRow(row) {
     return {
@@ -4869,9 +5214,10 @@ var ExperimentsLibSQL = class extends storage.ExperimentsStorage {
   }
   async getExperimentById(args) {
     try {
+      const scoped = buildScopedWhere("id", args.id, args.filters);
       const result = await this.#client.execute({
-        sql: `SELECT ${buildSelectColumns(storage.TABLE_EXPERIMENTS)} FROM ${storage.TABLE_EXPERIMENTS} WHERE id = ?`,
-        args: [args.id]
+        sql: `SELECT ${buildSelectColumns(storage.TABLE_EXPERIMENTS)} FROM ${storage.TABLE_EXPERIMENTS} WHERE ${scoped.sql}`,
+        args: scoped.args
       });
       return result.rows?.[0] ? this.transformExperimentRow(result.rows[0]) : null;
     } catch (error$1) {
@@ -4963,14 +5309,17 @@ var ExperimentsLibSQL = class extends storage.ExperimentsStorage {
   }
   async deleteExperiment(args) {
     try {
-      await this.#client.execute({
-        sql: `DELETE FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE experimentId = ?`,
-        args: [args.id]
-      });
-      await this.#client.execute({
-        sql: `DELETE FROM ${storage.TABLE_EXPERIMENTS} WHERE id = ?`,
-        args: [args.id]
-      });
+      const parentScoped = buildScopedWhere("id", args.id, args.filters);
+      const { conditions, params } = tenancyWhere(args.filters);
+      const cascadeWhere = conditions.length ? `experimentId IN (SELECT id FROM ${storage.TABLE_EXPERIMENTS} WHERE ${["id = ?", ...conditions].join(" AND ")})` : `experimentId = ?`;
+      const cascadeArgs = conditions.length ? [args.id, ...params] : [args.id];
+      await this.#client.batch(
+        [
+          { sql: `DELETE FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE ${cascadeWhere}`, args: cascadeArgs },
+          { sql: `DELETE FROM ${storage.TABLE_EXPERIMENTS} WHERE ${parentScoped.sql}`, args: parentScoped.args }
+        ],
+        "write"
+      );
     } catch (error$1) {
       throw new error.MastraError(
         {
@@ -5108,9 +5457,10 @@ var ExperimentsLibSQL = class extends storage.ExperimentsStorage {
   }
   async getExperimentResultById(args) {
     try {
+      const scoped = buildScopedWhere("id", args.id, args.filters);
       const result = await this.#client.execute({
-        sql: `SELECT ${buildSelectColumns(storage.TABLE_EXPERIMENT_RESULTS)} FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE id = ?`,
-        args: [args.id]
+        sql: `SELECT ${buildSelectColumns(storage.TABLE_EXPERIMENT_RESULTS)} FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE ${scoped.sql}`,
+        args: scoped.args
       });
       return result.rows?.[0] ? this.transformExperimentResultRow(result.rows[0]) : null;
     } catch (error$1) {
@@ -5190,6 +5540,14 @@ var ExperimentsLibSQL = class extends storage.ExperimentsStorage {
   }
   async deleteExperimentResults(args) {
     try {
+      const { conditions, params } = tenancyWhere(args.filters);
+      if (conditions.length) {
+        await this.#client.execute({
+          sql: `DELETE FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE experimentId IN (SELECT id FROM ${storage.TABLE_EXPERIMENTS} WHERE ${["id = ?", ...conditions].join(" AND ")})`,
+          args: [args.experimentId, ...params]
+        });
+        return;
+      }
       await this.#client.execute({
         sql: `DELETE FROM ${storage.TABLE_EXPERIMENT_RESULTS} WHERE experimentId = ?`,
         args: [args.experimentId]
@@ -5569,7 +5927,11 @@ function sessionToRecord(record) {
     deletedAt: record.deletedAt ?? null
   };
 }
-var HarnessLibSQL = class extends storage.HarnessStorage {
+var HarnessLibSQL = class _HarnessLibSQL extends storage.HarnessStorage {
+  /** Session records accumulate over time. Single table, anchored on `createdAt`. */
+  static retentionTables = {
+    sessions: { table: storage.TABLE_HARNESS_SESSIONS, column: "createdAt", indexed: true }
+  };
   #db;
   constructor(config) {
     super();
@@ -5585,6 +5947,15 @@ var HarnessLibSQL = class extends storage.HarnessStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.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: storage.TABLE_HARNESS_SESSIONS,
@@ -6570,8 +6941,18 @@ var MCPServersLibSQL = class extends storage.MCPServersStorage {
   }
 };
 var OM_TABLE = "mastra_observational_memory";
-var MemoryLibSQL = class extends storage.MemoryStorage {
+var MemoryLibSQL = class _MemoryLibSQL extends storage.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: storage.TABLE_MESSAGES, column: "createdAt", indexed: true },
+    resources: { table: storage.TABLE_RESOURCES, column: "createdAt", indexed: true },
+    threads: { table: storage.TABLE_THREADS, column: "createdAt", indexed: true }
+  };
   #client;
   #db;
   constructor(config) {
@@ -6646,6 +7027,21 @@ var MemoryLibSQL = class extends storage.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 {
@@ -8712,7 +9108,11 @@ function addArrayFilter(conditions, args, column, value) {
   conditions.push(`"${column}" IN (${values.map(() => "?").join(", ")})`);
   args.push(...values);
 }
-var NotificationsLibSQL = class extends storage.NotificationsStorage {
+var NotificationsLibSQL = class _NotificationsLibSQL extends storage.NotificationsStorage {
+  /** The notification feed grows unbounded. Single table, anchored on `createdAt`. */
+  static retentionTables = {
+    notifications: { table: storage.TABLE_NOTIFICATIONS, column: "createdAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -8747,6 +9147,15 @@ var NotificationsLibSQL = class extends storage.NotificationsStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.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) {
@@ -8936,7 +9345,14 @@ var NotificationsLibSQL = class extends storage.NotificationsStorage {
     return row ? rowToNotification(row) : void 0;
   }
 };
-var ObservabilityLibSQL = class extends storage.ObservabilityStorage {
+var ObservabilityLibSQL = class _ObservabilityLibSQL extends storage.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: storage.TABLE_SPANS, column: "startedAt", indexed: true }
+  };
   #db;
   constructor(config) {
     super();
@@ -8954,6 +9370,15 @@ var ObservabilityLibSQL = class extends storage.ObservabilityStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.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.
@@ -9962,7 +10387,15 @@ function rowToTrigger(row) {
   if (metadata !== void 0) trigger.metadata = metadata;
   return trigger;
 }
-var SchedulesLibSQL = class extends storage.SchedulesStorage {
+var SchedulesLibSQL = class _SchedulesLibSQL extends storage.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: storage.TABLE_SCHEDULE_TRIGGERS, column: "actual_fire_at", indexed: true, anchorType: "epoch-ms" }
+  };
   #db;
   #client;
   constructor(config) {
@@ -9998,6 +10431,15 @@ var SchedulesLibSQL = class extends storage.SchedulesStorage {
     await this.#db.deleteData({ tableName: storage.TABLE_SCHEDULE_TRIGGERS });
     await this.#db.deleteData({ tableName: storage.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) {
@@ -10672,7 +11114,23 @@ var ScorerDefinitionsLibSQL = class extends storage.ScorerDefinitionsStorage {
     };
   }
 };
-var ScoresLibSQL = class extends storage.ScoresStorage {
+function appendTenancyConditions(conditions, args, filters) {
+  if (filters?.organizationId !== void 0) {
+    conditions.push(`organizationId = ?`);
+    args.push(filters.organizationId);
+  }
+  if (filters?.projectId !== void 0) {
+    conditions.push(`projectId = ?`);
+    args.push(filters.projectId);
+  }
+}
+var ScoresLibSQL = class _ScoresLibSQL extends storage.ScoresStorage {
+  /**
+   * Scorer results accumulate as evals run. Single table, anchored on `createdAt`.
+   */
+  static retentionTables = {
+    scorers: { table: storage.TABLE_SCORERS, column: "createdAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -10686,21 +11144,35 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
     await this.#db.alterTable({
       tableName: storage.TABLE_SCORERS,
       schema: storage.SCORERS_SCHEMA,
-      ifNotExists: ["spanId", "requestContext"]
+      ifNotExists: ["spanId", "requestContext", "organizationId", "projectId", "batchId", "datasetId", "datasetItemId"]
     });
   }
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.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
+    pagination,
+    filters
   }) {
     try {
       const { page, perPage: perPageInput } = pagination;
+      const conditions = [`runId = ?`];
+      const queryParams = [runId];
+      appendTenancyConditions(conditions, queryParams, filters);
+      const whereClause = `WHERE ${conditions.join(" AND ")}`;
       const countResult = await this.#client.execute({
-        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} WHERE runId = ?`,
-        args: [runId]
+        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} ${whereClause}`,
+        args: queryParams
       });
       const total = Number(countResult.rows?.[0]?.count ?? 0);
       if (total === 0) {
@@ -10719,8 +11191,8 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
       const limitValue = perPageInput === false ? total : perPage;
       const end = perPageInput === false ? total : start + perPage;
       const result = await this.#client.execute({
-        sql: `SELECT ${buildSelectColumns(storage.TABLE_SCORERS)} FROM ${storage.TABLE_SCORERS} WHERE runId = ? ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
-        args: [runId, limitValue, start]
+        sql: `SELECT ${buildSelectColumns(storage.TABLE_SCORERS)} FROM ${storage.TABLE_SCORERS} ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        args: [...queryParams, limitValue, start]
       });
       const scores = result.rows?.map((row) => this.transformScoreRow(row)) ?? [];
       return {
@@ -10748,7 +11220,8 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
     entityId,
     entityType,
     source,
-    pagination
+    pagination,
+    filters
   }) {
     try {
       const { page, perPage: perPageInput } = pagination;
@@ -10770,6 +11243,7 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
         conditions.push(`source = ?`);
         queryParams.push(source);
       }
+      appendTenancyConditions(conditions, queryParams, filters);
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
       const countResult = await this.#client.execute({
         sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} ${whereClause}`,
@@ -10877,13 +11351,18 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
   async listScoresByEntityId({
     entityId,
     entityType,
-    pagination
+    pagination,
+    filters
   }) {
     try {
       const { page, perPage: perPageInput } = pagination;
+      const conditions = [`entityId = ?`, `entityType = ?`];
+      const queryParams = [entityId, entityType];
+      appendTenancyConditions(conditions, queryParams, filters);
+      const whereClause = `WHERE ${conditions.join(" AND ")}`;
       const countResult = await this.#client.execute({
-        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} WHERE entityId = ? AND entityType = ?`,
-        args: [entityId, entityType]
+        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} ${whereClause}`,
+        args: queryParams
       });
       const total = Number(countResult.rows?.[0]?.count ?? 0);
       if (total === 0) {
@@ -10902,8 +11381,8 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
       const limitValue = perPageInput === false ? total : perPage;
       const end = perPageInput === false ? total : start + perPage;
       const result = await this.#client.execute({
-        sql: `SELECT ${buildSelectColumns(storage.TABLE_SCORERS)} FROM ${storage.TABLE_SCORERS} WHERE entityId = ? AND entityType = ? ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
-        args: [entityId, entityType, limitValue, start]
+        sql: `SELECT ${buildSelectColumns(storage.TABLE_SCORERS)} FROM ${storage.TABLE_SCORERS} ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        args: [...queryParams, limitValue, start]
       });
       const scores = result.rows?.map((row) => this.transformScoreRow(row)) ?? [];
       return {
@@ -10929,22 +11408,27 @@ var ScoresLibSQL = class extends storage.ScoresStorage {
   async listScoresBySpan({
     traceId,
     spanId,
-    pagination
+    pagination,
+    filters
   }) {
     try {
       const { page, perPage: perPageInput } = pagination;
       const perPage = storage.normalizePerPage(perPageInput, 100);
       const { offset: start, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
+      const conditions = [`traceId = ?`, `spanId = ?`];
+      const queryParams = [traceId, spanId];
+      appendTenancyConditions(conditions, queryParams, filters);
+      const whereClause = `WHERE ${conditions.join(" AND ")}`;
       const countSQLResult = await this.#client.execute({
-        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} WHERE traceId = ? AND spanId = ?`,
-        args: [traceId, spanId]
+        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_SCORERS} ${whereClause}`,
+        args: queryParams
       });
       const total = Number(countSQLResult.rows?.[0]?.count ?? 0);
       const limitValue = perPageInput === false ? total : perPage;
       const end = perPageInput === false ? total : start + perPage;
       const result = await this.#client.execute({
-        sql: `SELECT ${buildSelectColumns(storage.TABLE_SCORERS)} FROM ${storage.TABLE_SCORERS} WHERE traceId = ? AND spanId = ? ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
-        args: [traceId, spanId, limitValue, start]
+        sql: `SELECT ${buildSelectColumns(storage.TABLE_SCORERS)} FROM ${storage.TABLE_SCORERS} ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        args: [...queryParams, limitValue, start]
       });
       const scores = result.rows?.map((row) => this.transformScoreRow(row)) ?? [];
       return {
@@ -11575,7 +12059,15 @@ var SkillsLibSQL = class extends storage.SkillsStorage {
     };
   }
 };
-var ThreadStateLibSQL = class extends storage.ThreadStateStorage {
+var ThreadStateLibSQL = class _ThreadStateLibSQL extends storage.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: storage.TABLE_THREAD_STATE, column: "updatedAt", indexed: true }
+  };
   #db;
   #client;
   constructor(config) {
@@ -11591,6 +12083,15 @@ var ThreadStateLibSQL = class extends storage.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 "${storage.TABLE_THREAD_STATE}"`);
@@ -11859,7 +12360,14 @@ var ToolProviderConnectionsLibSQL = class extends storage.ToolProviderConnection
     }
   }
 };
-var WorkflowsLibSQL = class extends storage.WorkflowsStorage {
+var WorkflowsLibSQL = class _WorkflowsLibSQL extends storage.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: storage.TABLE_WORKFLOW_SNAPSHOT, column: "updatedAt", indexed: true }
+  };
   #db;
   #client;
   executeWithRetry;
@@ -11912,6 +12420,15 @@ var WorkflowsLibSQL = class extends storage.WorkflowsStorage {
   async dangerouslyClearAll() {
     await this.#db.deleteData({ tableName: storage.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;");
@@ -12767,7 +13284,7 @@ var LibSQLStore = class extends storage.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;