@mastra/pg 1.14.3 → 1.15.0-alpha.1

package/dist/index.js

@@ -1,5 +1,5 @@
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { BRANCH_SPAN_TYPES, createVectorErrorId, AgentsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_SCHEMAS, createStorageErrorId, normalizePerPage, calculatePagination, BackgroundTasksStorage, TABLE_BACKGROUND_TASKS, BlobStore, TABLE_SKILL_BLOBS, ChannelsStorage, TABLE_CHANNEL_INSTALLATIONS, TABLE_CHANNEL_CONFIG, DatasetsStorage, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, DATASETS_SCHEMA, TABLE_CONFIGS, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, ensureDate, safelyParseJSON, ExperimentsStorage, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, FavoritesStorage, TABLE_FAVORITES, MCPClientsStorage, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, MCPServersStorage, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, MemoryStorage, TABLE_THREADS, TABLE_MESSAGES, TABLE_RESOURCES, NotificationsStorage, TABLE_NOTIFICATIONS, ObservabilityStorage, TABLE_SPANS, listTracesArgsSchema, toTraceSpans, PromptBlocksStorage, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, SchedulesStorage, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, ScorerDefinitionsStorage, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, ScoresStorage, TABLE_SCORERS, SkillsStorage, TABLE_SKILLS, TABLE_SKILL_VERSIONS, ToolProviderConnectionsStorage, TABLE_TOOL_PROVIDER_CONNECTIONS, WorkflowsStorage, TABLE_WORKFLOW_SNAPSHOT, mergeWorkflowStepResult, WorkspacesStorage, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, MastraCompositeStore, TraceStatus, getDefaultValue, listBranchesArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, transformScoreRow as transformScoreRow$1, getSqlType, EntityType, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
+import { BRANCH_SPAN_TYPES, createVectorErrorId, AgentsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_SCHEMAS, createStorageErrorId, normalizePerPage, calculatePagination, BackgroundTasksStorage, TABLE_BACKGROUND_TASKS, BlobStore, TABLE_SKILL_BLOBS, ChannelsStorage, TABLE_CHANNEL_INSTALLATIONS, TABLE_CHANNEL_CONFIG, DatasetsStorage, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, DATASETS_SCHEMA, TABLE_CONFIGS, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, ensureDate, safelyParseJSON, ExperimentsStorage, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, FavoritesStorage, TABLE_FAVORITES, MCPClientsStorage, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, MCPServersStorage, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, MemoryStorage, TABLE_THREADS, TABLE_RESOURCES, TABLE_MESSAGES, NotificationsStorage, TABLE_NOTIFICATIONS, ObservabilityStorage, TABLE_SPANS, listTracesArgsSchema, toTraceSpans, PromptBlocksStorage, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, SchedulesStorage, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, ScorerDefinitionsStorage, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, ScoresStorage, TABLE_SCORERS, SkillsStorage, TABLE_SKILLS, TABLE_SKILL_VERSIONS, ToolProviderConnectionsStorage, TABLE_TOOL_PROVIDER_CONNECTIONS, WorkflowsStorage, TABLE_WORKFLOW_SNAPSHOT, mergeWorkflowStepResult, WorkspacesStorage, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, MastraCompositeStore, TraceStatus, getDefaultValue, parseDuration, listBranchesArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, transformScoreRow as transformScoreRow$1, getSqlType, EntityType, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
 import { parseSqlIdentifier, parseFieldKey } from '@mastra/core/utils';
 import { MastraVector, validateTopK, validateUpsertInput } from '@mastra/core/vector';
 import { Mutex } from 'async-mutex';
@@ -2517,6 +2517,11 @@ CREATE TRIGGER ${triggerName}
     EXECUTE FUNCTION ${functionName}();`;
 }
 var schemaSetupRegistry = /* @__PURE__ */ new Map();
+function assertPositiveLimit(limit) {
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new Error(`prune limit must be a positive integer; received ${limit}`);
+  }
+}
 var PgDB = class extends MastraBase {
   client;
   schemaName;
@@ -3553,6 +3558,96 @@ Note: This migration may take some time for large tables.
   async deleteData({ tableName }) {
     return this.clearTable({ tableName });
   }
+  // ---------------------------------------------------------------------------
+  // Retention helpers (prune)
+  // ---------------------------------------------------------------------------
+  /**
+   * Deletes up to `limit` rows from `tableName` whose `column` value is strictly
+   * older than `cutoff`, in a single bounded statement. Returns the number of
+   * rows deleted so the caller's batch loop can decide whether the table is
+   * drained.
+   *
+   * PostgreSQL has no `DELETE ... LIMIT`, so this targets a bounded set of
+   * physical rows via the `ctid` system column (PG's row identity, analogous to
+   * SQLite's `rowid`). `cutoff` is bound as a parameter — a `Date`/ISO-8601
+   * string compared against a `timestamptz` anchor column, or a `number`
+   * compared against a `bigint` epoch-ms anchor column.
+   */
+  async pruneBatch({
+    tableName,
+    column,
+    cutoff,
+    limit
+  }) {
+    assertPositiveLimit(limit);
+    const fullTableName = getTableName({ indexName: tableName, schemaName: getSchemaName(this.schemaName) });
+    const parsedColumn = `"${parseSqlIdentifier(column, "column name")}"`;
+    const sql = `
+      DELETE FROM ${fullTableName}
+      WHERE ctid IN (
+        SELECT ctid FROM ${fullTableName}
+        WHERE ${parsedColumn} < $1
+        LIMIT $2
+      )
+    `;
+    const result = await this.client.query(sql, [cutoff, limit]);
+    return result.rowCount ?? 0;
+  }
+  /**
+   * Deletes up to `limit` aged parent rows *and* their child rows together, in
+   * a single transaction (used by whole-unit pruning such as experiments →
+   * experiment_results). The aged parent IDs are selected first and both
+   * deletes target that exact ID set, so a bound or abort between batches never
+   * leaves a parent hollow (kept, but with its children gone) or children
+   * orphaned.
+   */
+  async pruneUnitsBatch({
+    parentTable,
+    parentKey,
+    parentColumn,
+    childTable,
+    childForeignKey,
+    cutoff,
+    limit
+  }) {
+    assertPositiveLimit(limit);
+    const schemaName = getSchemaName(this.schemaName);
+    const fullChildTable = getTableName({ indexName: childTable, schemaName });
+    const fullParentTable = getTableName({ indexName: parentTable, schemaName });
+    const childFk = `"${parseSqlIdentifier(childForeignKey, "column name")}"`;
+    const parentPk = `"${parseSqlIdentifier(parentKey, "column name")}"`;
+    const parentCol = `"${parseSqlIdentifier(parentColumn, "column name")}"`;
+    return this.client.tx(async (t) => {
+      const rows = await t.manyOrNone(
+        `SELECT ${parentPk} AS id FROM ${fullParentTable} WHERE ${parentCol} < $1 LIMIT $2 FOR UPDATE SKIP LOCKED`,
+        [cutoff, limit]
+      );
+      const ids = rows.map((r) => r.id);
+      if (ids.length === 0) return { parents: 0, children: 0 };
+      const childResult = await t.query(`DELETE FROM ${fullChildTable} WHERE ${childFk} = ANY($1)`, [ids]);
+      const parentResult = await t.query(`DELETE FROM ${fullParentTable} WHERE ${parentPk} = ANY($1)`, [ids]);
+      return {
+        parents: parentResult.rowCount ?? 0,
+        children: childResult.rowCount ?? 0
+      };
+    });
+  }
+  /**
+   * Creates a btree index on `column` for `tableName` if it does not already
+   * exist, so age-based prune deletes stay fast. Delegates to {@link createIndex}
+   * (which is a no-op when the index is present).
+   *
+   * The name is lowercased and truncated to Postgres' 63-byte identifier limit
+   * (schema-prefixed names can exceed it), mirroring {@link buildConstraintName}.
+   */
+  async ensureIndex({
+    indexName,
+    tableName,
+    column
+  }) {
+    const name = buildConstraintName({ baseName: indexName });
+    await this.createIndex({ name, table: tableName, columns: [column] });
+  }
   async executeUpdate(client, {
     tableName,
     keys,
@@ -3628,6 +3723,20 @@ function transformFromSqlRow({
   });
   return result;
 }
+function tenancyWhere(filters, startIndex) {
+  const conditions = [];
+  const params = [];
+  let idx = startIndex;
+  if (filters?.organizationId !== void 0) {
+    conditions.push(`"organizationId" = $${idx++}`);
+    params.push(filters.organizationId);
+  }
+  if (filters?.projectId !== void 0) {
+    conditions.push(`"projectId" = $${idx++}`);
+    params.push(filters.projectId);
+  }
+  return { conditions, params, nextIndex: idx };
+}
 
 // src/storage/domains/agents/index.ts
 var AgentsPG = class _AgentsPG extends AgentsStorage {
@@ -4511,6 +4620,98 @@ var AgentsPG = class _AgentsPG extends AgentsStorage {
     };
   }
 };
+var DEFAULT_BATCH_SIZE = 1e3;
+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);
+}
+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
+}) {
+  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;
+    }
+    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",
+      policy
+    });
+  }
+  return targets;
+}
+
+// src/storage/domains/background-tasks/index.ts
 function getSchemaName3(schema) {
   return schema ? `"${schema}"` : '"public"';
 }
@@ -4565,6 +4766,14 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends BackgroundTasksStorage
   #skipDefaultIndexes;
   #indexes;
   static MANAGED_TABLES = [TABLE_BACKGROUND_TASKS];
+  /**
+   * Completed background tasks accumulate as dead weight. Anchored on the
+   * timezone-aware `completedAtZ` mirror column: NULL (in-flight) rows are
+   * excluded automatically since `completedAtZ < cutoff` is false for NULL.
+   */
+  static retentionTables = {
+    backgroundTasks: { table: TABLE_BACKGROUND_TASKS, column: "completedAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -4586,6 +4795,40 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends BackgroundTasksStorage
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_BackgroundTasksPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
+  /** Delete completed tasks older than the `backgroundTasks` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _BackgroundTasksPG.retentionTables,
+      order: ["backgroundTasks"]
+    });
+    return runPrune({ db: this.#db, domain: "backgroundTasks", targets, options });
+  }
   static getDefaultIndexDefs(schemaPrefix) {
     return [
       {
@@ -5349,8 +5592,8 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
           groundTruthSchema: input.groundTruthSchema ?? null,
           requestContextSchema: input.requestContextSchema ?? null,
           targetType: input.targetType ?? null,
-          targetIds: input.targetIds !== void 0 ? JSON.stringify(input.targetIds) : null,
-          scorerIds: input.scorerIds ? JSON.stringify(input.scorerIds) : null,
+          targetIds: input.targetIds ?? null,
+          scorerIds: input.scorerIds ?? null,
           organizationId: input.organizationId ?? null,
           projectId: input.projectId ?? null,
           candidateKey: input.candidateKey ?? null,
@@ -5390,10 +5633,15 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
       );
     }
   }
-  async getDatasetById({ id }) {
+  async getDatasetById({
+    id,
+    filters
+  }) {
     try {
       const tableName = getTableName2({ indexName: TABLE_DATASETS, schemaName: getSchemaName2(this.#schema) });
-      const result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1`, [id]);
+      const { conditions, params } = tenancyWhere(filters, 2);
+      const whereSql = ['"id" = $1', ...conditions].join(" AND ");
+      const result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE ${whereSql}`, [id, ...params]);
       return result ? this.transformDatasetRow(result) : null;
     } catch (error) {
       throw new MastraError(
@@ -5408,7 +5656,7 @@ var DatasetsPG = class _DatasetsPG extends 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 MastraError({
           id: createStorageErrorId("PG", "UPDATE_DATASET", "NOT_FOUND"),
@@ -5497,7 +5745,7 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
       );
     }
   }
-  async deleteDataset({ id }) {
+  async deleteDataset({ id, filters }) {
     try {
       const datasetsTable = getTableName2({ indexName: TABLE_DATASETS, schemaName: getSchemaName2(this.#schema) });
       const itemsTable = getTableName2({ indexName: TABLE_DATASET_ITEMS, schemaName: getSchemaName2(this.#schema) });
@@ -5510,24 +5758,31 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
         indexName: TABLE_EXPERIMENT_RESULTS,
         schemaName: getSchemaName2(this.#schema)
       });
-      try {
-        await this.#db.client.none(
-          `DELETE FROM ${experimentResultsTable} WHERE "experimentId" IN (SELECT "id" FROM ${experimentsTable} WHERE "datasetId" = $1)`,
-          [id]
-        );
-      } catch {
-      }
-      try {
-        await this.#db.client.none(
-          `UPDATE ${experimentsTable} SET "datasetId" = NULL, "datasetVersion" = NULL WHERE "datasetId" = $1`,
-          [id]
-        );
-      } catch {
-      }
+      const { conditions, params } = tenancyWhere(filters, 2);
+      const scopedWhere = ['"id" = $1', ...conditions].join(" AND ");
       await this.#db.client.tx(async (t) => {
+        const locked = await t.oneOrNone(`SELECT "id" FROM ${datasetsTable} WHERE ${scopedWhere} FOR UPDATE`, [
+          id,
+          ...params
+        ]);
+        if (!locked) return;
+        const experimentTablesExist = await t.oneOrNone(
+          `SELECT to_regclass($1) IS NOT NULL AND to_regclass($2) IS NOT NULL AS exists`,
+          [experimentResultsTable, experimentsTable]
+        );
+        if (experimentTablesExist?.exists) {
+          await t.none(
+            `DELETE FROM ${experimentResultsTable} WHERE "experimentId" IN (SELECT "id" FROM ${experimentsTable} WHERE "datasetId" = $1)`,
+            [id]
+          );
+          await t.none(
+            `UPDATE ${experimentsTable} SET "datasetId" = NULL, "datasetVersion" = NULL WHERE "datasetId" = $1`,
+            [id]
+          );
+        }
         await t.none(`DELETE FROM ${versionsTable} WHERE "datasetId" = $1`, [id]);
         await t.none(`DELETE FROM ${itemsTable} WHERE "datasetId" = $1`, [id]);
-        await t.none(`DELETE FROM ${datasetsTable} WHERE "id" = $1`, [id]);
+        await t.none(`DELETE FROM ${datasetsTable} WHERE ${scopedWhere}`, [id, ...params]);
       });
     } catch (error) {
       if (error instanceof MastraError) throw error;
@@ -5549,7 +5804,7 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
       const queryParams = [];
       let paramIndex = 1;
       if (args.filters) {
-        const { organizationId, projectId, candidateKey, candidateId } = args.filters;
+        const { organizationId, projectId, candidateKey, candidateId, targetType, targetIds, name } = args.filters;
         if (organizationId !== void 0) {
           conditions.push(`"organizationId" = $${paramIndex++}`);
           queryParams.push(organizationId);
@@ -5566,6 +5821,18 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
           conditions.push(`"candidateId" = $${paramIndex++}`);
           queryParams.push(candidateId);
         }
+        if (targetType !== void 0) {
+          conditions.push(`"targetType" = $${paramIndex++}`);
+          queryParams.push(targetType);
+        }
+        if (targetIds !== void 0 && targetIds.length > 0) {
+          conditions.push(`"targetIds" ?| $${paramIndex++}::text[]`);
+          queryParams.push(targetIds);
+        }
+        if (name !== void 0 && name.length > 0) {
+          conditions.push(`"name" ILIKE $${paramIndex++}`);
+          queryParams.push(`%${name}%`);
+        }
       }
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
       const countResult = await this.#db.client.one(
@@ -6223,12 +6490,24 @@ var DatasetsPG = class _DatasetsPG extends DatasetsStorage {
     await this.#db.clearTable({ tableName: TABLE_DATASETS });
   }
 };
+var DEFAULT_PRUNE_BATCH_SIZE = 1e3;
 var ExperimentsPG = class _ExperimentsPG extends ExperimentsStorage {
   #db;
   #schema;
   #skipDefaultIndexes;
   #indexes;
   static MANAGED_TABLES = [TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS];
+  /**
+   * Experiments prune as whole units: an aged experiment and its result rows go
+   * together, mirroring `deleteExperiment`. Anchored on `completedAt` (not the
+   * `completedAtZ` mirror, which carries a `DEFAULT NOW()` this domain never
+   * overrides — it holds insert time even for running rows). `completedAt` is
+   * written as a UTC ISO string and stays NULL while running, so
+   * `completedAt < cutoff` is false for in-flight experiments.
+   */
+  static retentionTables = {
+    experiments: { table: TABLE_EXPERIMENTS, column: "completedAt", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -6267,6 +6546,75 @@ var ExperimentsPG = class _ExperimentsPG extends ExperimentsStorage {
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_ExperimentsPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
+  /**
+   * Delete experiments whose `completedAt` is older than the 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 }
+      ] : [];
+    }
+    await this.ensureRetentionIndexes(policies);
+    const rawCutoff = cutoffFor(policy, "timestamp");
+    const cutoff = rawCutoff instanceof Date ? rawCutoff.toISOString() : rawCutoff;
+    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 }
+    ];
+  }
   getDefaultIndexDefinitions() {
     return [
       { name: "idx_experiments_datasetid", table: TABLE_EXPERIMENTS, columns: ["datasetId"] },
@@ -6496,10 +6844,15 @@ var ExperimentsPG = class _ExperimentsPG extends ExperimentsStorage {
       );
     }
   }
-  async getExperimentById({ id }) {
+  async getExperimentById({
+    id,
+    filters
+  }) {
     try {
       const tableName = getTableName2({ indexName: TABLE_EXPERIMENTS, schemaName: getSchemaName2(this.#schema) });
-      const result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1`, [id]);
+      const { conditions, params } = tenancyWhere(filters, 2);
+      const whereSql = ['"id" = $1', ...conditions].join(" AND ");
+      const result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE ${whereSql}`, [id, ...params]);
       return result ? this.transformExperimentRow(result) : null;
     } catch (error) {
       throw new MastraError(
@@ -6586,15 +6939,21 @@ var ExperimentsPG = class _ExperimentsPG extends ExperimentsStorage {
       );
     }
   }
-  async deleteExperiment({ id }) {
+  async deleteExperiment({ id, filters }) {
     try {
       const resultsTable = getTableName2({
         indexName: TABLE_EXPERIMENT_RESULTS,
         schemaName: getSchemaName2(this.#schema)
       });
       const experimentsTable = getTableName2({ indexName: TABLE_EXPERIMENTS, schemaName: getSchemaName2(this.#schema) });
-      await this.#db.client.none(`DELETE FROM ${resultsTable} WHERE "experimentId" = $1`, [id]);
-      await this.#db.client.none(`DELETE FROM ${experimentsTable} WHERE "id" = $1`, [id]);
+      const { conditions, params } = tenancyWhere(filters, 2);
+      const gateSql = `SELECT "id" FROM ${experimentsTable} WHERE ${['"id" = $1', ...conditions].join(" AND ")} FOR UPDATE`;
+      await this.#db.client.tx(async (t) => {
+        const parent = await t.oneOrNone(gateSql, [id, ...params]);
+        if (!parent) return;
+        await t.none(`DELETE FROM ${resultsTable} WHERE "experimentId" = $1`, [id]);
+        await t.none(`DELETE FROM ${experimentsTable} WHERE "id" = $1`, [id]);
+      });
     } catch (error) {
       throw new MastraError(
         {
@@ -6724,10 +7083,15 @@ var ExperimentsPG = class _ExperimentsPG extends ExperimentsStorage {
       );
     }
   }
-  async getExperimentResultById({ id }) {
+  async getExperimentResultById({
+    id,
+    filters
+  }) {
     try {
       const tableName = getTableName2({ indexName: TABLE_EXPERIMENT_RESULTS, schemaName: getSchemaName2(this.#schema) });
-      const result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE "id" = $1`, [id]);
+      const { conditions, params } = tenancyWhere(filters, 2);
+      const whereSql = ['"id" = $1', ...conditions].join(" AND ");
+      const result = await this.#db.client.oneOrNone(`SELECT * FROM ${tableName} WHERE ${whereSql}`, [id, ...params]);
       return result ? this.transformExperimentResultRow(result) : null;
     } catch (error) {
       throw new MastraError(
@@ -6802,9 +7166,23 @@ var ExperimentsPG = class _ExperimentsPG extends ExperimentsStorage {
       );
     }
   }
-  async deleteExperimentResults({ experimentId }) {
+  async deleteExperimentResults({
+    experimentId,
+    filters
+  }) {
     try {
       const tableName = getTableName2({ indexName: TABLE_EXPERIMENT_RESULTS, schemaName: getSchemaName2(this.#schema) });
+      const experimentsTable = getTableName2({ indexName: TABLE_EXPERIMENTS, schemaName: getSchemaName2(this.#schema) });
+      if (filters?.organizationId !== void 0 || filters?.projectId !== void 0) {
+        const { conditions, params } = tenancyWhere(filters, 2);
+        const gateSql = `SELECT "id" FROM ${experimentsTable} WHERE ${['"id" = $1', ...conditions].join(" AND ")} FOR UPDATE`;
+        await this.#db.client.tx(async (t) => {
+          const parent = await t.oneOrNone(gateSql, [experimentId, ...params]);
+          if (!parent) return;
+          await t.none(`DELETE FROM ${tableName} WHERE "experimentId" = $1`, [experimentId]);
+        });
+        return;
+      }
       await this.#db.client.none(`DELETE FROM ${tableName} WHERE "experimentId" = $1`, [experimentId]);
     } catch (error) {
       throw new MastraError(
@@ -8435,6 +8813,18 @@ function dedupeMessagesForSave(messages) {
 }
 var MemoryPG = class _MemoryPG extends MemoryStorage {
   supportsObservationalMemory = true;
+  /**
+   * Retention-eligible tables. `threads`, `messages`, and `resources` all anchor
+   * on the timezone-aware `createdAtZ` mirror column (kept in sync by triggers),
+   * and are indexed for fast batched deletes. Cascade order is enforced in
+   * `prune()` (children before threads), not here. Observational memory has no
+   * timestamp anchor and is deliberately excluded.
+   */
+  static retentionTables = {
+    messages: { table: TABLE_MESSAGES, column: "createdAtZ", indexed: true },
+    resources: { table: TABLE_RESOURCES, column: "createdAtZ", indexed: true },
+    threads: { table: TABLE_THREADS, column: "createdAtZ", indexed: true }
+  };
   #db;
   #schema;
   #skipDefaultIndexes;
@@ -8480,6 +8870,30 @@ var MemoryPG = class _MemoryPG extends MemoryStorage {
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema && this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_MemoryPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
   /**
    * Returns default index definitions for the memory domain tables.
    * @param schemaPrefix - Prefix for index names (e.g. "my_schema_" or "")
@@ -8580,6 +8994,76 @@ var MemoryPG = class _MemoryPG extends MemoryStorage {
     await this.#db.clearTable({ tableName: TABLE_THREADS });
     await this.#db.clearTable({ tableName: TABLE_RESOURCES });
   }
+  /**
+   * Deletes rows older than the configured `maxAge` per table, in bounded,
+   * batched, cancellable chunks. Tables are pruned children-first (messages and
+   * resources before threads) since PostgreSQL has no FK cascade in this schema.
+   * Unset tables are kept forever.
+   *
+   * When a `messages` policy is set, semantic-recall embeddings for pruned
+   * messages are also swept from same-schema `memory_messages*` vector tables
+   * (best-effort, mirroring `deleteThread`). Embeddings held in an external
+   * vector store are out of reach and must be pruned by the operator.
+   */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _MemoryPG.retentionTables,
+      order: ["messages", "resources", "threads"]
+    });
+    const results = await runPrune({ db: this.#db, domain: "memory", targets, options });
+    if (policies["messages"]) {
+      await this.pruneOrphanedVectorRows(policies["messages"], options);
+    }
+    return results;
+  }
+  /**
+   * Best-effort sweep of semantic-recall vector rows whose source message no
+   * longer exists (e.g. it was just pruned), so recall doesn't keep returning
+   * embeddings that resolve to nothing. Only same-schema default vector tables
+   * (`memory_messages*`) are covered — the same set `deleteThread` cleans up.
+   * Failures are logged, never thrown: vector cleanup must not fail the prune.
+   */
+  async pruneOrphanedVectorRows(policy, options) {
+    try {
+      const schemaName = this.#schema || "public";
+      const vectorTables = await this.#db.client.manyOrNone(
+        `
+        SELECT tablename
+        FROM pg_tables
+        WHERE schemaname = $1
+        AND (tablename = 'memory_messages' OR tablename LIKE 'memory_messages_%')
+      `,
+        [schemaName]
+      );
+      const messagesTable = getTableName4({ indexName: TABLE_MESSAGES, schemaName: getSchemaName4(this.#schema) });
+      for (const { tablename } of vectorTables) {
+        const vectorTableName = getTableName4({ indexName: tablename, schemaName: getSchemaName4(this.#schema) });
+        await runBatchedDelete({
+          deleteBatch: async (limit) => {
+            const result = await this.#db.client.query(
+              `
+              DELETE FROM ${vectorTableName}
+              WHERE ctid IN (
+                SELECT v.ctid FROM ${vectorTableName} v
+                WHERE v.metadata->>'message_id' IS NOT NULL
+                AND NOT EXISTS (SELECT 1 FROM ${messagesTable} m WHERE m.id = v.metadata->>'message_id')
+                LIMIT $1
+              )
+            `,
+              [limit]
+            );
+            return result.rowCount ?? 0;
+          },
+          batchSize: policy.batchSize ?? 1e3,
+          options
+        });
+      }
+    } catch (error) {
+      this.logger?.warn?.("Failed to sweep orphaned semantic-recall vector rows after prune:", error);
+    }
+  }
   /**
    * Normalizes message row from database by applying createdAtZ fallback
    */
@@ -10891,6 +11375,13 @@ var NotificationsPG = class _NotificationsPG extends NotificationsStorage {
   #skipDefaultIndexes;
   #indexes;
   static MANAGED_TABLES = [TABLE_NOTIFICATIONS];
+  /**
+   * Notifications are an append-only event feed that grows unbounded. Single
+   * table, anchored on the timezone-aware `createdAtZ` mirror column.
+   */
+  static retentionTables = {
+    notifications: { table: TABLE_NOTIFICATIONS, column: "createdAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -10907,6 +11398,40 @@ var NotificationsPG = class _NotificationsPG extends NotificationsStorage {
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema && this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_NotificationsPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
+  /** Delete notifications older than the `notifications` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _NotificationsPG.retentionTables,
+      order: ["notifications"]
+    });
+    return runPrune({ db: this.#db, domain: "notifications", targets, options });
+  }
   static getDefaultIndexDefs(schemaPrefix) {
     return [
       {
@@ -11148,6 +11673,14 @@ var NotificationsPG = class _NotificationsPG extends NotificationsStorage {
   }
 };
 var ObservabilityPG = class _ObservabilityPG extends ObservabilityStorage {
+  /**
+   * Retention-eligible tables. The observability domain has a single physical
+   * table (`mastra_ai_spans`); spans anchor on the timezone-aware `startedAtZ`
+   * mirror column and are indexed for fast batched deletes.
+   */
+  static retentionTables = {
+    spans: { table: TABLE_SPANS, column: "startedAtZ", indexed: true }
+  };
   #db;
   #schema;
   #skipDefaultIndexes;
@@ -11172,6 +11705,30 @@ var ObservabilityPG = class _ObservabilityPG extends ObservabilityStorage {
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large span tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_ObservabilityPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
   /**
    * Returns default index definitions for the observability domain tables.
    * @param schemaPrefix - Prefix for index names (e.g. "my_schema_" or "")
@@ -11316,6 +11873,19 @@ var ObservabilityPG = class _ObservabilityPG extends ObservabilityStorage {
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: TABLE_SPANS });
   }
+  /**
+   * Deletes spans older than the configured `maxAge`, in bounded, batched,
+   * cancellable chunks. Unset = keep forever.
+   */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _ObservabilityPG.retentionTables,
+      order: ["spans"]
+    });
+    return runPrune({ db: this.#db, domain: "observability", targets, options });
+  }
   get tracingStrategy() {
     return {
       preferred: "batch-with-updates",
@@ -14012,6 +14582,78 @@ async function setupPartitioning(client, schema, options = {}) {
       return "native";
   }
 }
+function retentionCutoff(policy, now = Date.now()) {
+  return new Date(now - parseDuration(policy.maxAge));
+}
+async function listChildPartitions(client, schema, table) {
+  const rows = await client.manyOrNone(
+    `SELECT c.relname AS "name", pg_get_expr(c.relpartbound, c.oid) AS "bound"
+     FROM pg_inherits i
+     JOIN pg_class c ON c.oid = i.inhrelid
+     JOIN pg_class p ON p.oid = i.inhparent
+     JOIN pg_namespace n ON n.oid = p.relnamespace
+     WHERE n.nspname = $1 AND p.relname = $2`,
+    [schema, table]
+  );
+  const partitions = [];
+  for (const row of rows ?? []) {
+    const match = /TO \('([^']+)'\)/.exec(row.bound ?? "");
+    if (!match?.[1]) continue;
+    const upperBound = new Date(match[1]);
+    if (Number.isNaN(upperBound.getTime())) continue;
+    partitions.push({ name: row.name, upperBound });
+  }
+  return partitions.sort((a, b) => a.upperBound.getTime() - b.upperBound.getTime());
+}
+async function prunePartitionedTable({
+  client,
+  schema,
+  table,
+  cutoff,
+  options
+}) {
+  const partitions = await listChildPartitions(client, schema, table);
+  const droppable = partitions.filter((p) => p.upperBound.getTime() <= cutoff.getTime());
+  let deleted = 0;
+  let batches = 0;
+  for (const partition of droppable) {
+    if (options?.signal?.aborted) return { deleted, done: false };
+    if (options?.maxBatches !== void 0 && batches >= options.maxBatches) return { deleted, done: false };
+    if (options?.maxRows !== void 0 && deleted >= options.maxRows) return { deleted, done: false };
+    const child = qualifiedName(schema, partition.name);
+    const parent = qualifiedTable(schema, table);
+    const row = await client.one(`SELECT count(*)::int AS "n" FROM ${child}`);
+    await client.none(`ALTER TABLE ${parent} DETACH PARTITION ${child}`);
+    await client.none(`DROP TABLE IF EXISTS ${child}`);
+    deleted += row.n;
+    batches += 1;
+  }
+  return { deleted, done: true };
+}
+async function pruneTimescaleTable({
+  client,
+  schema,
+  table,
+  cutoff,
+  options
+}) {
+  if (options?.signal?.aborted || options?.maxBatches === 0) return { deleted: 0, done: false };
+  const tableExpr = qualifiedTable(schema, table);
+  const chunks = await client.manyOrNone(
+    `SELECT show_chunks($1::regclass, older_than => $2::timestamptz)::text AS "chunk"`,
+    [tableExpr, cutoff.toISOString()]
+  );
+  let deleted = 0;
+  for (const { chunk } of chunks ?? []) {
+    const row = await client.one(`SELECT count(*)::int AS "n" FROM ${chunk}`);
+    deleted += row.n;
+  }
+  await client.none(`SELECT drop_chunks($1::regclass, older_than => $2::timestamptz)`, [
+    tableExpr,
+    cutoff.toISOString()
+  ]);
+  return { deleted, done: true };
+}
 function applyScoreFilters(acc, filters) {
   applyCommonFilters(acc, filters);
   applySingleOrArrayFilter(acc, "scorerId", filters?.scorerId);
@@ -14758,7 +15400,7 @@ function wrapError(op, error, details) {
     error
   );
 }
-var ObservabilityStoragePostgresVNext = class extends ObservabilityStorage {
+var ObservabilityStoragePostgresVNext = class _ObservabilityStoragePostgresVNext extends ObservabilityStorage {
   #client;
   #schema;
   #partitioning;
@@ -14842,6 +15484,50 @@ var ObservabilityStoragePostgresVNext = class extends ObservabilityStorage {
   get partitionMode() {
     return this.#partitionMode;
   }
+  // -------------------------------------------------------------------------
+  // Retention
+  // -------------------------------------------------------------------------
+  /**
+   * All five signal tables are insert-only growth tables. The anchor column is
+   * each table's partition / chunk key, so age-based expiry drops whole day
+   * partitions instead of deleting rows (see `./retention.ts`). `indexed: true`
+   * reflects that expiry never scans — it acts on partition bounds.
+   */
+  static retentionTables = {
+    spans: { table: TABLE_SPAN_EVENTS, column: "endedAt", indexed: true },
+    metrics: { table: TABLE_METRIC_EVENTS, column: "timestamp", indexed: true },
+    logs: { table: TABLE_LOG_EVENTS, column: "timestamp", indexed: true },
+    scores: { table: TABLE_SCORE_EVENTS, column: "timestamp", indexed: true },
+    feedback: { table: TABLE_FEEDBACK_EVENTS, column: "timestamp", indexed: true }
+  };
+  /**
+   * Expire signal events older than each table's `maxAge` by dropping whole
+   * day partitions (native / pg_partman) or chunks (Timescale). Only
+   * partitions wholly older than the cutoff are dropped, so the effective
+   * granularity is one day. Each partition drop counts as one batch for
+   * `maxBatches` / `maxRows` / abort-signal purposes; `deleted` reports the
+   * row count of the dropped partitions.
+   */
+  async prune(policies, options) {
+    return this.#run("VNEXT_PRUNE", async () => {
+      const mode = this.#partitionMode ??= await resolveMode(this.#client, this.#partitioning);
+      const results = [];
+      const now = Date.now();
+      for (const [key, entry] of Object.entries(_ObservabilityStoragePostgresVNext.retentionTables)) {
+        const policy = policies[key];
+        if (!policy) continue;
+        if (options?.signal?.aborted) {
+          results.push({ domain: "observability", table: entry.table, deleted: 0, done: false });
+          continue;
+        }
+        const cutoff = retentionCutoff(policy, now);
+        const args = { client: this.#client, schema: this.#schema, table: entry.table, cutoff, options };
+        const outcome = mode === "timescale" ? await pruneTimescaleTable(args) : await prunePartitionedTable(args);
+        results.push({ domain: "observability", table: entry.table, deleted: outcome.deleted, done: outcome.done });
+      }
+      return results;
+    });
+  }
   get observabilityStrategy() {
     return { preferred: "insert-only", supported: ["insert-only"] };
   }
@@ -15786,6 +16472,15 @@ var SchedulesPG = class _SchedulesPG extends SchedulesStorage {
   #indexes;
   /** Tables managed by this domain */
   static MANAGED_TABLES = [TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS];
+  /**
+   * 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
+   * timestamptz).
+   */
+  static retentionTables = {
+    triggers: { table: TABLE_SCHEDULE_TRIGGERS, column: "actual_fire_at", indexed: true, anchorType: "epoch-ms" }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -15807,6 +16502,43 @@ var SchedulesPG = class _SchedulesPG extends SchedulesStorage {
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast. The default
+   * composite index leads with `schedule_id`, so a bare `actual_fire_at` range
+   * scan can't use it. Called from the prune path (not init) so only
+   * deployments that configure retention pay the index's write/disk overhead.
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_SchedulesPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
+  /**
+   * Delete trigger (fire history) rows whose `actual_fire_at` is older than the
+   * `triggers` policy's `maxAge`, batched. Schedule definitions are never pruned.
+   */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _SchedulesPG.retentionTables,
+      order: ["triggers"]
+    });
+    return runPrune({ db: this.#db, domain: "schedules", targets, options });
+  }
   /**
    * Returns default index definitions for the schedules domain.
    * @param schemaPrefix - Prefix for index names (e.g. "my_schema_" or "")
@@ -16139,6 +16871,11 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
       tableName: TABLE_SCORER_DEFINITIONS,
       schema: TABLE_SCHEMAS[TABLE_SCORER_DEFINITIONS]
     });
+    await this.#db.alterTable({
+      tableName: TABLE_SCORER_DEFINITIONS,
+      schema: TABLE_SCHEMAS[TABLE_SCORER_DEFINITIONS],
+      ifNotExists: ["organizationId", "projectId"]
+    });
     await this.#db.createTable({
       tableName: TABLE_SCORER_DEFINITION_VERSIONS,
       schema: TABLE_SCHEMAS[TABLE_SCORER_DEFINITION_VERSIONS]
@@ -16194,14 +16931,16 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
       const nowIso = now.toISOString();
       await this.#db.client.none(
         `INSERT INTO ${tableName} (
-          id, status, "activeVersionId", "authorId", metadata,
+          id, status, "activeVersionId", "authorId", "organizationId", "projectId", metadata,
           "createdAt", "createdAtZ", "updatedAt", "updatedAtZ"
-        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
         [
           scorerDefinition.id,
           "draft",
           null,
           scorerDefinition.authorId ?? null,
+          scorerDefinition.organizationId ?? null,
+          scorerDefinition.projectId ?? null,
           scorerDefinition.metadata ? JSON.stringify(scorerDefinition.metadata) : null,
           nowIso,
           nowIso,
@@ -16209,7 +16948,14 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
           nowIso
         ]
       );
-      const { id: _id, authorId: _authorId, metadata: _metadata, ...snapshotConfig } = scorerDefinition;
+      const {
+        id: _id,
+        authorId: _authorId,
+        organizationId: _organizationId,
+        projectId: _projectId,
+        metadata: _metadata,
+        ...snapshotConfig
+      } = scorerDefinition;
       const versionId = crypto.randomUUID();
       await this.createVersion({
         id: versionId,
@@ -16224,6 +16970,8 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
         status: "draft",
         activeVersionId: void 0,
         authorId: scorerDefinition.authorId,
+        organizationId: scorerDefinition.organizationId,
+        projectId: scorerDefinition.projectId,
         metadata: scorerDefinition.metadata,
         createdAt: now,
         updatedAt: now
@@ -16337,7 +17085,16 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
     }
   }
   async list(args) {
-    const { page = 0, perPage: perPageInput, orderBy, authorId, metadata, status } = args || {};
+    const {
+      page = 0,
+      perPage: perPageInput,
+      orderBy,
+      authorId,
+      organizationId,
+      projectId,
+      metadata,
+      status
+    } = args || {};
     const { field, direction } = this.parseOrderBy(orderBy);
     if (page < 0) {
       throw new MastraError(
@@ -16365,6 +17122,14 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
         conditions.push(`"authorId" = $${paramIdx++}`);
         queryParams.push(authorId);
       }
+      if (organizationId !== void 0) {
+        conditions.push(`"organizationId" = $${paramIdx++}`);
+        queryParams.push(organizationId);
+      }
+      if (projectId !== void 0) {
+        conditions.push(`"projectId" = $${paramIdx++}`);
+        queryParams.push(projectId);
+      }
       if (metadata && Object.keys(metadata).length > 0) {
         conditions.push(`metadata @> $${paramIdx++}::jsonb`);
         queryParams.push(JSON.stringify(metadata));
@@ -16691,6 +17456,8 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
       status: row.status,
       activeVersionId: row.activeVersionId,
       authorId: row.authorId,
+      organizationId: row.organizationId,
+      projectId: row.projectId,
       metadata: parseJsonResilient(row.metadata),
       createdAt: new Date(row.createdAtZ || row.createdAt),
       updatedAt: new Date(row.updatedAtZ || row.updatedAt)
@@ -16715,6 +17482,18 @@ var ScorerDefinitionsPG = class _ScorerDefinitionsPG extends ScorerDefinitionsSt
     };
   }
 };
+function applyTenancyFilters(conditions, queryParams, startIndex, filters) {
+  let paramIndex = startIndex;
+  if (filters?.organizationId !== void 0) {
+    conditions.push(`"organizationId" = $${paramIndex++}`);
+    queryParams.push(filters.organizationId);
+  }
+  if (filters?.projectId !== void 0) {
+    conditions.push(`"projectId" = $${paramIndex++}`);
+    queryParams.push(filters.projectId);
+  }
+  return paramIndex;
+}
 function getSchemaName6(schema) {
   return schema ? `"${schema}"` : '"public"';
 }
@@ -16737,6 +17516,13 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
   #indexes;
   /** Tables managed by this domain */
   static MANAGED_TABLES = [TABLE_SCORERS];
+  /**
+   * Scorer results accumulate as evals run. Single table, anchored on the
+   * timezone-aware `createdAtZ` mirror column (kept in sync by triggers).
+   */
+  static retentionTables = {
+    scorers: { table: TABLE_SCORERS, column: "createdAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -16750,11 +17536,35 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
     await this.#db.alterTable({
       tableName: TABLE_SCORERS,
       schema: TABLE_SCHEMAS[TABLE_SCORERS],
-      ifNotExists: ["spanId", "requestContext"]
+      ifNotExists: ["spanId", "requestContext", "organizationId", "projectId", "batchId", "datasetId", "datasetItemId"]
     });
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema && this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_ScoresPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
   /**
    * Returns default index definitions for the scores domain tables.
    * @param schemaPrefix - Prefix for index names (e.g. "my_schema_" or "")
@@ -16829,6 +17639,16 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: TABLE_SCORERS });
   }
+  /** Delete scorer results older than the `scorers` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _ScoresPG.retentionTables,
+      order: ["scorers"]
+    });
+    return runPrune({ db: this.#db, domain: "scores", targets, options });
+  }
   async getScoreById({ id }) {
     try {
       const result = await this.#db.client.oneOrNone(
@@ -16852,7 +17672,8 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
     pagination,
     entityId,
     entityType,
-    source
+    source,
+    filters
   }) {
     try {
       const conditions = [`"scorerId" = $1`];
@@ -16870,6 +17691,7 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
         conditions.push(`"source" = $${paramIndex++}`);
         queryParams.push(source);
       }
+      paramIndex = applyTenancyFilters(conditions, queryParams, paramIndex, filters);
       const whereClause = conditions.join(" AND ");
       const total = await this.#db.client.oneOrNone(
         `SELECT COUNT(*) FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE ${whereClause}`,
@@ -16983,12 +17805,17 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
   }
   async listScoresByRunId({
     runId,
-    pagination
+    pagination,
+    filters
   }) {
     try {
+      const conditions = [`"runId" = $1`];
+      const queryParams = [runId];
+      let paramIndex = applyTenancyFilters(conditions, queryParams, 2, filters);
+      const whereClause = conditions.join(" AND ");
       const total = await this.#db.client.oneOrNone(
-        `SELECT COUNT(*) FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE "runId" = $1`,
-        [runId]
+        `SELECT COUNT(*) FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE ${whereClause}`,
+        queryParams
       );
       const { page, perPage: perPageInput } = pagination;
       const perPage = normalizePerPage(perPageInput, 100);
@@ -17007,8 +17834,8 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
       const limitValue = perPageInput === false ? Number(total?.count) : perPage;
       const end = perPageInput === false ? Number(total?.count) : start + perPage;
       const result = await this.#db.client.manyOrNone(
-        `SELECT * FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE "runId" = $1 LIMIT $2 OFFSET $3`,
-        [runId, limitValue, start]
+        `SELECT * FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE ${whereClause} ORDER BY "createdAt" DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
+        [...queryParams, limitValue, start]
       );
       return {
         pagination: {
@@ -17033,12 +17860,17 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
   async listScoresByEntityId({
     entityId,
     entityType,
-    pagination
+    pagination,
+    filters
   }) {
     try {
+      const conditions = [`"entityId" = $1`, `"entityType" = $2`];
+      const queryParams = [entityId, entityType];
+      let paramIndex = applyTenancyFilters(conditions, queryParams, 3, filters);
+      const whereClause = conditions.join(" AND ");
       const total = await this.#db.client.oneOrNone(
-        `SELECT COUNT(*) FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE "entityId" = $1 AND "entityType" = $2`,
-        [entityId, entityType]
+        `SELECT COUNT(*) FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE ${whereClause}`,
+        queryParams
       );
       const { page, perPage: perPageInput } = pagination;
       const perPage = normalizePerPage(perPageInput, 100);
@@ -17057,8 +17889,8 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
       const limitValue = perPageInput === false ? Number(total?.count) : perPage;
       const end = perPageInput === false ? Number(total?.count) : start + perPage;
       const result = await this.#db.client.manyOrNone(
-        `SELECT * FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE "entityId" = $1 AND "entityType" = $2 LIMIT $3 OFFSET $4`,
-        [entityId, entityType, limitValue, start]
+        `SELECT * FROM ${getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) })} WHERE ${whereClause} ORDER BY "createdAt" DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
+        [...queryParams, limitValue, start]
       );
       return {
         pagination: {
@@ -17083,13 +17915,18 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
   async listScoresBySpan({
     traceId,
     spanId,
-    pagination
+    pagination,
+    filters
   }) {
     try {
       const tableName = getTableName6({ indexName: TABLE_SCORERS, schemaName: getSchemaName6(this.#schema) });
+      const conditions = [`"traceId" = $1`, `"spanId" = $2`];
+      const queryParams = [traceId, spanId];
+      let paramIndex = applyTenancyFilters(conditions, queryParams, 3, filters);
+      const whereClause = conditions.join(" AND ");
       const countSQLResult = await this.#db.client.oneOrNone(
-        `SELECT COUNT(*) as count FROM ${tableName} WHERE "traceId" = $1 AND "spanId" = $2`,
-        [traceId, spanId]
+        `SELECT COUNT(*) as count FROM ${tableName} WHERE ${whereClause}`,
+        queryParams
       );
       const total = Number(countSQLResult?.count ?? 0);
       const { page, perPage: perPageInput } = pagination;
@@ -17098,8 +17935,8 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
       const limitValue = perPageInput === false ? total : perPage;
       const end = perPageInput === false ? total : start + perPage;
       const result = await this.#db.client.manyOrNone(
-        `SELECT * FROM ${tableName} WHERE "traceId" = $1 AND "spanId" = $2 ORDER BY "createdAt" DESC LIMIT $3 OFFSET $4`,
-        [traceId, spanId, limitValue, start]
+        `SELECT * FROM ${tableName} WHERE ${whereClause} ORDER BY "createdAt" DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
+        [...queryParams, limitValue, start]
       );
       const hasMore = end < total;
       const scores = result.map((row) => transformScoreRow(row)) ?? [];
@@ -18150,6 +18987,14 @@ var WorkflowsPG = class _WorkflowsPG extends WorkflowsStorage {
   #indexes;
   /** Tables managed by this domain */
   static MANAGED_TABLES = [TABLE_WORKFLOW_SNAPSHOT];
+  /**
+   * Workflow run snapshots accumulate as runs execute. Anchored on the
+   * timezone-aware `updatedAtZ` mirror column (last activity) so suspended or
+   * long-running runs are not pruned by start age.
+   */
+  static retentionTables = {
+    workflowSnapshot: { table: TABLE_WORKFLOW_SNAPSHOT, column: "updatedAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -18221,6 +19066,40 @@ var WorkflowsPG = class _WorkflowsPG extends WorkflowsStorage {
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
+  /**
+   * Lazily ensures a btree index exists on each configured policy's retention
+   * anchor column so age-based `prune()` deletes stay fast on large tables.
+   * Called from the prune path (not init) so only deployments that configure
+   * retention pay the index's write/disk overhead. Best-effort: failures are
+   * logged and pruning proceeds (correct, just slower).
+   * Created even with `skipDefaultIndexes` — retention is an explicit opt-in,
+   * so its supporting index is not part of the default index set.
+   */
+  async ensureRetentionIndexes(policies) {
+    const prefix = this.#schema && this.#schema !== "public" ? `${this.#schema}_` : "";
+    for (const [key, entry] of Object.entries(_WorkflowsPG.retentionTables)) {
+      if (!entry.indexed || !policies[key]) continue;
+      try {
+        await this.#db.ensureIndex({
+          indexName: `${prefix}mastra_${key}_retention_idx`,
+          tableName: entry.table,
+          column: entry.column
+        });
+      } catch (error) {
+        this.logger?.warn?.(`Failed to create retention index for ${entry.table}:`, error);
+      }
+    }
+  }
+  /** Delete workflow run snapshots older than the `workflowSnapshot` policy's `maxAge`, batched. */
+  async prune(policies, options) {
+    await this.ensureRetentionIndexes(policies);
+    const targets = resolveTargets({
+      policies,
+      descriptor: _WorkflowsPG.retentionTables,
+      order: ["workflowSnapshot"]
+    });
+    return runPrune({ db: this.#db, domain: "workflows", targets, options });
+  }
   /**
    * Creates custom user-defined indexes for this domain's tables.
    */
@@ -19334,7 +20213,7 @@ var PostgresStore = class extends MastraCompositeStore {
   constructor(config) {
     try {
       validateConfig("PostgresStore", config);
-      super({ id: config.id, name: "PostgresStore", disableInit: config.disableInit });
+      super({ id: config.id, name: "PostgresStore", disableInit: config.disableInit, retention: config.retention });
       this.schema = parseSqlIdentifier(config.schemaName || "public", "schema name");
       if (isPoolConfig(config)) {
         this.#pool = config.pool;