@mastra/spanner 1.9.4 → 1.9.5

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-spanner
 description: Documentation for @mastra/spanner. Use when working with @mastra/spanner APIs, configuration, or implementation.
 metadata:
   package: "@mastra/spanner"
-  version: "1.9.4"
+  version: "1.9.5"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.4",
+  "version": "1.9.5",
   "package": "@mastra/spanner",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-storage-retention.md

@@ -12,18 +12,21 @@ Retention covers **growth tables** only: tables that accumulate rows unbounded a
 
 Storage adapters use the shared core retention contract for `prune()`, or a database-native mechanism when that better matches the backend.
 
-| Adapter              | Mechanism               | Retention support                                                                                                                                                                      |
-| -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| libSQL               | `prune()`               | All supported growth domains                                                                                                                                                           |
-| PostgreSQL           | `prune()`               | All supported growth domains. vNext observability drops expired partitions or chunks                                                                                                   |
-| MongoDB              | `prune()` or native TTL | All supported growth domains. Native TTL indexes are also available                                                                                                                    |
-| DuckDB               | `prune()`               | Observability spans, metrics, logs, scores, and feedback                                                                                                                               |
-| MySQL                | `prune()`               | Observability spans                                                                                                                                                                    |
-| Microsoft SQL Server | `prune()`               | Observability spans                                                                                                                                                                    |
-| Oracle Database      | `prune()`               | Observability spans and logs                                                                                                                                                           |
-| Amazon Aurora DSQL   | `prune()`               | Observability spans                                                                                                                                                                    |
-| Google Cloud Spanner | `prune()`               | Observability spans, plus metrics when metrics storage is enabled                                                                                                                      |
-| ClickHouse           | Native TTL              | Observability spans, metrics, logs, scores, and feedback. When all five signals have finite retention, deletion-request records expire after the longest signal retention plus 30 days |
+| Adapter                           | Mechanism               | Retention support                                                                                                                                                                      |
+| --------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| libSQL                            | `prune()`               | All supported growth domains                                                                                                                                                           |
+| PostgreSQL                        | `prune()`               | All supported growth domains. vNext observability drops expired partitions or chunks                                                                                                   |
+| MongoDB                           | `prune()` or native TTL | All supported growth domains. Native TTL indexes are also available                                                                                                                    |
+| DuckDB                            | `prune()`               | Observability spans, metrics, logs, scores, and feedback                                                                                                                               |
+| MySQL                             | `prune()`               | Observability spans, durable agent run fencing (`runOwnership`, `runFences`)                                                                                                           |
+| Microsoft SQL Server              | `prune()`               | Observability spans, durable agent run fencing (`runOwnership`, `runFences`)                                                                                                           |
+| Oracle Database                   | `prune()`               | Observability spans and logs, durable agent run fencing (`runOwnership`, `runFences`)                                                                                                  |
+| Amazon Aurora DSQL                | `prune()`               | Observability spans, durable agent run fencing (`runOwnership`, `runFences`)                                                                                                           |
+| Google Cloud Spanner              | `prune()`               | Observability spans, plus metrics when metrics storage is enabled. Durable agent run fencing (`runOwnership`, `runFences`)                                                             |
+| DynamoDB                          | `prune()`               | Durable agent run fencing (`runOwnership`, `runFences`)                                                                                                                                |
+| Convex                            | `prune()`               | Durable agent run fencing (`runOwnership`, `runFences`). Redeploy your Convex functions after upgrading                                                                                |
+| Cloudflare D1 and Durable Objects | `prune()`               | Durable agent run fencing (`runOwnership`, `runFences`)                                                                                                                                |
+| ClickHouse                        | Native TTL              | Observability spans, metrics, logs, scores, and feedback. When all five signals have finite retention, deletion-request records expire after the longest signal retention plus 30 days |
 
 ## Storage-specific maintenance
 

package/dist/index.cjs

@@ -273,6 +273,51 @@ var SpannerDB = class extends _mastra_core_base.MastraBase {
 		}
 	}
 	/**
+	* Delete up to `limit` rows keyed by `runId` whose epoch-ms `column` is
+	* older than `cutoff`. Used to prune the run fencing tables.
+	*/
+	async pruneRunRows({ tableName, column, cutoff, limit }) {
+		const table = quoteIdent(tableName, "table name");
+		const col = quoteIdent(column, "column name");
+		const runId = quoteIdent("runId", "column name");
+		const [rows] = await this.database.run({
+			sql: `SELECT ${runId} FROM ${table} WHERE ${col} IS NOT NULL AND ${col} < @cutoff ORDER BY ${col} LIMIT @limit`,
+			params: {
+				cutoff,
+				limit
+			},
+			types: {
+				cutoff: "int64",
+				limit: "int64"
+			},
+			json: true
+		});
+		const runIds = rows.map((row) => row.runId);
+		if (runIds.length === 0) return 0;
+		let deleted = 0;
+		await this.runWithAbortRetry(async () => {
+			await this.database.runTransactionAsync(async (tx) => {
+				const [count] = await tx.runUpdate({
+					sql: `DELETE FROM ${table} WHERE ${runId} IN UNNEST(@runIds) AND ${col} < @cutoff`,
+					params: {
+						runIds,
+						cutoff
+					},
+					types: {
+						runIds: {
+							type: "array",
+							child: "string"
+						},
+						cutoff: "int64"
+					}
+				});
+				await tx.commit();
+				deleted = count;
+			});
+		});
+		return deleted;
+	}
+	/**
 	* Determine the primary-key column list for a table. Some core tables (like
 	* `mastra_workflow_snapshot`) don't carry a single-column PK in the schema,
 	* so we hardcode known composite PKs here.
@@ -6761,6 +6806,17 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		_mastra_core_storage.TABLE_MESSAGES,
 		_mastra_core_storage.TABLE_RESOURCES
 	];
+	/**
+	* Tables `prune()` can clean up. Run fences anchor on `retiredAt` (epoch ms), which stays NULL until the
+	* execution holding the fence settles, so a running execution's fence is
+	* never pruned.
+	*/
+	static retentionTables = { runFences: {
+		table: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES,
+		column: "retiredAt",
+		indexed: false,
+		anchorType: "epoch-ms"
+	} };
 	constructor(config) {
 		super();
 		const { database, indexes, skipDefaultIndexes, initMode } = resolveSpannerConfig(config);
@@ -6817,6 +6873,24 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		await this.db.createIndexes(this.indexes);
 	}
 	/** Removes every row from threads/messages/resources and run fence tables. Intended for tests. */
+	async prune(policies, options) {
+		return (0, _mastra_core_storage.executeRetentionPrune)({
+			domain: "memory",
+			targets: (0, _mastra_core_storage.resolveRetentionTargets)({
+				policies,
+				descriptor: MemorySpanner.retentionTables,
+				order: ["runFences"]
+			}),
+			options,
+			cutoffFor: (target, now) => (0, _mastra_core_storage.retentionCutoffMs)(target.policy, now),
+			deleteBatch: (target, cutoff, limit) => this.db.pruneRunRows({
+				tableName: target.table,
+				column: target.column,
+				cutoff,
+				limit
+			})
+		});
+	}
 	async dangerouslyClearAll() {
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_MESSAGES });
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_THREADS });
@@ -12479,6 +12553,17 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 	skipDefaultIndexes;
 	indexes;
 	static MANAGED_TABLES = [_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT];
+	/**
+	* Tables `prune()` can clean up. Run ownership rows anchor on `updatedAt` (epoch ms), which every
+	* claim, renewal and release refreshes, so a live execution's row is never
+	* older than its renew interval.
+	*/
+	static retentionTables = { runOwnership: {
+		table: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS,
+		column: "updatedAt",
+		indexed: false,
+		anchorType: "epoch-ms"
+	} };
 	constructor(config) {
 		super();
 		const { database, indexes, skipDefaultIndexes, initMode } = resolveSpannerConfig(config);
@@ -12611,6 +12696,24 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		await this.db.createIndexes(this.indexes);
 	}
 	/** Removes every workflow snapshot and run ownership row. Intended for tests. */
+	async prune(policies, options) {
+		return (0, _mastra_core_storage.executeRetentionPrune)({
+			domain: "workflows",
+			targets: (0, _mastra_core_storage.resolveRetentionTargets)({
+				policies,
+				descriptor: WorkflowsSpanner.retentionTables,
+				order: ["runOwnership"]
+			}),
+			options,
+			cutoffFor: (target, now) => (0, _mastra_core_storage.retentionCutoffMs)(target.policy, now),
+			deleteBatch: (target, cutoff, limit) => this.db.pruneRunRows({
+				tableName: target.table,
+				column: target.column,
+				cutoff,
+				limit
+			})
+		});
+	}
 	async dangerouslyClearAll() {
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT });
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS });