@mastra/pg 1.14.3 → 1.15.0-alpha.0

package/dist/index.cjs

@@ -2542,6 +2542,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 base.MastraBase {
   client;
   schemaName;
@@ -3578,6 +3583,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 = `"${utils.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 = `"${utils.parseSqlIdentifier(childForeignKey, "column name")}"`;
+    const parentPk = `"${utils.parseSqlIdentifier(parentKey, "column name")}"`;
+    const parentCol = `"${utils.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,
@@ -4536,6 +4631,98 @@ var AgentsPG = class _AgentsPG extends storage.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 - storage.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"';
 }
@@ -4590,6 +4777,14 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
   #skipDefaultIndexes;
   #indexes;
   static MANAGED_TABLES = [storage.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: storage.TABLE_BACKGROUND_TASKS, column: "completedAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -4611,6 +4806,40 @@ var BackgroundTasksPG = class _BackgroundTasksPG extends storage.BackgroundTasks
     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 [
       {
@@ -6248,12 +6477,24 @@ var DatasetsPG = class _DatasetsPG extends storage.DatasetsStorage {
     await this.#db.clearTable({ tableName: storage.TABLE_DATASETS });
   }
 };
+var DEFAULT_PRUNE_BATCH_SIZE = 1e3;
 var ExperimentsPG = class _ExperimentsPG extends storage.ExperimentsStorage {
   #db;
   #schema;
   #skipDefaultIndexes;
   #indexes;
   static MANAGED_TABLES = [storage.TABLE_EXPERIMENTS, storage.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: storage.TABLE_EXPERIMENTS, column: "completedAt", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -6292,6 +6533,75 @@ var ExperimentsPG = class _ExperimentsPG extends storage.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: storage.TABLE_EXPERIMENT_RESULTS, deleted: 0, done: false },
+        { domain: "experiments", table: storage.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: storage.TABLE_EXPERIMENTS,
+          parentKey: "id",
+          parentColumn: "completedAt",
+          childTable: storage.TABLE_EXPERIMENT_RESULTS,
+          childForeignKey: "experimentId",
+          cutoff,
+          limit
+        });
+        childDeleted += children;
+        return parents;
+      },
+      batchSize,
+      options
+    });
+    return [
+      { domain: "experiments", table: storage.TABLE_EXPERIMENT_RESULTS, deleted: childDeleted, done: parent.done },
+      { domain: "experiments", table: storage.TABLE_EXPERIMENTS, deleted: parent.deleted, done: parent.done }
+    ];
+  }
   getDefaultIndexDefinitions() {
     return [
       { name: "idx_experiments_datasetid", table: storage.TABLE_EXPERIMENTS, columns: ["datasetId"] },
@@ -8460,6 +8770,18 @@ function dedupeMessagesForSave(messages) {
 }
 var MemoryPG = class _MemoryPG extends storage.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: storage.TABLE_MESSAGES, column: "createdAtZ", indexed: true },
+    resources: { table: storage.TABLE_RESOURCES, column: "createdAtZ", indexed: true },
+    threads: { table: storage.TABLE_THREADS, column: "createdAtZ", indexed: true }
+  };
   #db;
   #schema;
   #skipDefaultIndexes;
@@ -8505,6 +8827,30 @@ var MemoryPG = class _MemoryPG extends storage.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 "")
@@ -8605,6 +8951,76 @@ var MemoryPG = class _MemoryPG extends storage.MemoryStorage {
     await this.#db.clearTable({ tableName: storage.TABLE_THREADS });
     await this.#db.clearTable({ tableName: storage.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: storage.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
    */
@@ -10916,6 +11332,13 @@ var NotificationsPG = class _NotificationsPG extends storage.NotificationsStorag
   #skipDefaultIndexes;
   #indexes;
   static MANAGED_TABLES = [storage.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: storage.TABLE_NOTIFICATIONS, column: "createdAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -10932,6 +11355,40 @@ var NotificationsPG = class _NotificationsPG extends storage.NotificationsStorag
     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 [
       {
@@ -11173,6 +11630,14 @@ var NotificationsPG = class _NotificationsPG extends storage.NotificationsStorag
   }
 };
 var ObservabilityPG = class _ObservabilityPG extends storage.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: storage.TABLE_SPANS, column: "startedAtZ", indexed: true }
+  };
   #db;
   #schema;
   #skipDefaultIndexes;
@@ -11197,6 +11662,30 @@ var ObservabilityPG = class _ObservabilityPG extends storage.ObservabilityStorag
     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 "")
@@ -11341,6 +11830,19 @@ var ObservabilityPG = class _ObservabilityPG extends storage.ObservabilityStorag
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: storage.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",
@@ -14037,6 +14539,78 @@ async function setupPartitioning(client, schema, options = {}) {
       return "native";
   }
 }
+function retentionCutoff(policy, now = Date.now()) {
+  return new Date(now - storage.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);
@@ -14783,7 +15357,7 @@ function wrapError(op, error$1, details) {
     error$1
   );
 }
-var ObservabilityStoragePostgresVNext = class extends storage.ObservabilityStorage {
+var ObservabilityStoragePostgresVNext = class _ObservabilityStoragePostgresVNext extends storage.ObservabilityStorage {
   #client;
   #schema;
   #partitioning;
@@ -14867,6 +15441,50 @@ var ObservabilityStoragePostgresVNext = class extends storage.ObservabilityStora
   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"] };
   }
@@ -15811,6 +16429,15 @@ var SchedulesPG = class _SchedulesPG extends storage.SchedulesStorage {
   #indexes;
   /** Tables managed by this domain */
   static MANAGED_TABLES = [storage.TABLE_SCHEDULES, storage.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: storage.TABLE_SCHEDULE_TRIGGERS, column: "actual_fire_at", indexed: true, anchorType: "epoch-ms" }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -15832,6 +16459,43 @@ var SchedulesPG = class _SchedulesPG extends storage.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 "")
@@ -16762,6 +17426,13 @@ var ScoresPG = class _ScoresPG extends storage.ScoresStorage {
   #indexes;
   /** Tables managed by this domain */
   static MANAGED_TABLES = [storage.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: storage.TABLE_SCORERS, column: "createdAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -16780,6 +17451,30 @@ var ScoresPG = class _ScoresPG extends storage.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 "")
@@ -16854,6 +17549,16 @@ var ScoresPG = class _ScoresPG extends storage.ScoresStorage {
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: storage.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(
@@ -18175,6 +18880,14 @@ var WorkflowsPG = class _WorkflowsPG extends storage.WorkflowsStorage {
   #indexes;
   /** Tables managed by this domain */
   static MANAGED_TABLES = [storage.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: storage.TABLE_WORKFLOW_SNAPSHOT, column: "updatedAtZ", indexed: true }
+  };
   constructor(config) {
     super();
     const { client, schemaName, skipDefaultIndexes, indexes } = resolvePgConfig(config);
@@ -18246,6 +18959,40 @@ var WorkflowsPG = class _WorkflowsPG extends storage.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.
    */
@@ -19359,7 +20106,7 @@ var PostgresStore = class extends storage.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 = utils.parseSqlIdentifier(config.schemaName || "public", "schema name");
       if (isPoolConfig(config)) {
         this.#pool = config.pool;