@mastra/pg 1.14.3 → 1.15.0-alpha.0

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,
@@ -4511,6 +4606,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 +4752,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 +4781,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 [
       {
@@ -6223,12 +6452,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 +6508,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"] },
@@ -8435,6 +8745,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 +8802,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 +8926,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 +11307,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 +11330,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 +11605,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 +11637,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 +11805,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 +14514,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 +15332,7 @@ function wrapError(op, error, details) {
     error
   );
 }
-var ObservabilityStoragePostgresVNext = class extends ObservabilityStorage {
+var ObservabilityStoragePostgresVNext = class _ObservabilityStoragePostgresVNext extends ObservabilityStorage {
   #client;
   #schema;
   #partitioning;
@@ -14842,6 +15416,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 +16404,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 +16434,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 "")
@@ -16737,6 +17401,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);
@@ -16755,6 +17426,30 @@ var ScoresPG = class _ScoresPG extends ScoresStorage {
     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 +17524,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(
@@ -18150,6 +18855,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 +18934,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 +20081,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;