@mastra/spanner 1.9.3 → 1.9.4-alpha.0

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.3"
+  version: "1.9.4-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.3",
+  "version": "1.9.4-alpha.0",
   "package": "@mastra/spanner",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -6657,6 +6657,59 @@ var MCPServersSpanner = class MCPServersSpanner extends _mastra_core_storage.MCP
 	}
 };
 //#endregion
+//#region src/storage/db/run-fencing.ts
+/** Epoch milliseconds on the database clock, read when the statement runs. */
+const DB_NOW_MS = "UNIX_MILLIS(CURRENT_TIMESTAMP())";
+/**
+* The check half of a fenced write; call it first inside the write's
+* read-write transaction. Reads in a read-write transaction lock the rows they
+* return until commit, so a claim that updates the row either waits for the
+* write to commit or aborts it, and the retried write sees the new claim.
+*/
+async function assertRunFence(tx, claimsTable, fence, operation) {
+	const [rows] = await tx.run({
+		sql: `SELECT generation, ${quoteIdent("ownerId", "column name")} AS ownerId
+          FROM ${quoteIdent(claimsTable, "table name")}
+          WHERE ${quoteIdent("runId", "column name")} = @runId`,
+		params: { runId: fence.runId },
+		json: true
+	});
+	const row = rows[0];
+	if (!(0, _mastra_core_storage.matchesRunFence)(row ? {
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId)
+	} : null, fence)) throw new _mastra_core_storage.RunFenceConflictError(fence, operation);
+}
+/**
+* Runs `fn` in a read-write transaction and commits it, retrying the whole
+* transaction when Spanner aborts it for conflicting with another one.
+*/
+function inTransaction(db, fn) {
+	return db.runWithAbortRetry(() => db.database.runTransactionAsync(async (tx) => {
+		try {
+			const result = await fn(tx);
+			await tx.commit();
+			return result;
+		} catch (err) {
+			await tx.rollback().catch((rollbackErr) => {
+				throw new AggregateError([err, rollbackErr], "Transaction and rollback both failed");
+			});
+			throw err;
+		}
+	}));
+}
+/**
+* Runs `write` directly when it carries no fence, or in a transaction behind
+* the fence check when it does.
+*/
+function withRunFence(db, claimsTable, fence, operation, write) {
+	if (!fence) return write(void 0);
+	return inTransaction(db, async (tx) => {
+		await assertRunFence(tx, claimsTable, fence, operation);
+		return write(tx);
+	});
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 function buildSpannerMessageMetadataFilter(metadataFilter) {
 	if (!metadataFilter) return {
@@ -6720,7 +6773,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		this.skipDefaultIndexes = skipDefaultIndexes;
 		this.indexes = indexes?.filter((idx) => MemorySpanner.MANAGED_TABLES.includes(idx.table));
 	}
-	/** Creates the threads/messages/resources tables and any indexes. */
+	/** Creates the threads/messages/resources and run fence tables and any indexes. */
 	async init() {
 		await this.db.createTable({
 			tableName: _mastra_core_storage.TABLE_THREADS,
@@ -6734,6 +6787,10 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 			tableName: _mastra_core_storage.TABLE_RESOURCES,
 			schema: _mastra_core_storage.TABLE_SCHEMAS[_mastra_core_storage.TABLE_RESOURCES]
 		});
+		await this.db.createTable({
+			tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_MEMORY_RUN_FENCES]
+		});
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
 	}
@@ -6759,11 +6816,92 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		if (!this.indexes || this.indexes.length === 0) return;
 		await this.db.createIndexes(this.indexes);
 	}
-	/** Removes every row from threads/messages/resources tables. Intended for tests. */
+	/** Removes every row from threads/messages/resources and run fence tables. Intended for tests. */
 	async dangerouslyClearAll() {
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_MESSAGES });
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_THREADS });
 		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_RESOURCES });
+		await this.db.clearTable({ tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES });
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async raiseRunFence(fence) {
+		const table = quoteIdent(_mastra_core_storage.TABLE_MEMORY_RUN_FENCES, "table name");
+		const runIdCol = quoteIdent("runId", "column name");
+		const ownerIdCol = quoteIdent("ownerId", "column name");
+		const retiredAtCol = quoteIdent("retiredAt", "column name");
+		try {
+			return await inTransaction(this.db, async (tx) => {
+				const [rows] = await tx.run({
+					sql: `SELECT generation, ${ownerIdCol} AS ownerId FROM ${table} WHERE ${runIdCol} = @runId`,
+					params: { runId: fence.runId },
+					json: true
+				});
+				const row = rows[0];
+				if (!row) {
+					await tx.runUpdate({
+						sql: `INSERT INTO ${table} (${runIdCol}, generation, ${ownerIdCol}) VALUES (@runId, @generation, @ownerId)`,
+						params: {
+							runId: fence.runId,
+							generation: fence.generation,
+							ownerId: fence.ownerId
+						}
+					});
+					return true;
+				}
+				const generation = Number(row.generation);
+				const raises = generation < fence.generation;
+				const reaffirms = generation === fence.generation && String(row.ownerId) === fence.ownerId;
+				if (!raises && !reaffirms) return false;
+				await tx.runUpdate({
+					sql: `UPDATE ${table} SET generation = @generation, ${ownerIdCol} = @ownerId, ${retiredAtCol} = NULL
+                WHERE ${runIdCol} = @runId`,
+					params: {
+						runId: fence.runId,
+						generation: fence.generation,
+						ownerId: fence.ownerId
+					}
+				});
+				return true;
+			});
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "RAISE_RUN_FENCE", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	async retireRunFence(fence) {
+		const table = quoteIdent(_mastra_core_storage.TABLE_MEMORY_RUN_FENCES, "table name");
+		try {
+			return await inTransaction(this.db, async (tx) => {
+				const [count] = await tx.runUpdate({
+					sql: `UPDATE ${table} SET ${quoteIdent("retiredAt", "column name")} = ${DB_NOW_MS}
+                WHERE ${quoteIdent("runId", "column name")} = @runId AND generation = @generation
+                  AND ${quoteIdent("ownerId", "column name")} = @ownerId`,
+					params: {
+						runId: fence.runId,
+						generation: fence.generation,
+						ownerId: fence.ownerId
+					}
+				});
+				return count === 1;
+			});
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "RETIRE_RUN_FENCE", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	/** The fence check for a write already running in a read-write transaction. */
+	async #assertFence(tx, fence, operation) {
+		if (fence) await assertRunFence(tx, _mastra_core_storage.TABLE_MEMORY_RUN_FENCES, fence, operation);
 	}
 	/**
 	* Fetches a thread row by id, or `null` when absent.
@@ -6932,9 +7070,9 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		}
 	}
 	/** Upserts a thread row by id (`INSERT OR UPDATE` semantics). */
-	async saveThread({ thread }) {
+	async saveThread({ thread, fence }) {
 		try {
-			await this.db.upsert({
+			await withRunFence(this.db, _mastra_core_storage.TABLE_MEMORY_RUN_FENCES, (0, _mastra_core_storage.resolveRunFence)(this, fence), "saveThread", (tx) => this.db.upsert({
 				tableName: _mastra_core_storage.TABLE_THREADS,
 				record: {
 					id: thread.id,
@@ -6943,10 +7081,12 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 					metadata: thread.metadata ?? {},
 					createdAt: thread.createdAt,
 					updatedAt: thread.updatedAt
-				}
-			});
+				},
+				transaction: tx
+			}));
 			return thread;
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "SAVE_THREAD", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -6956,7 +7096,8 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		}
 	}
 	/** Updates a thread's title and merges the metadata payload. */
-	async updateThread({ id, title, metadata }) {
+	async updateThread({ id, title, metadata, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence);
 		const tableThreads = quoteIdent(_mastra_core_storage.TABLE_THREADS, "table name");
 		const now = /* @__PURE__ */ new Date();
 		let merged = {};
@@ -6964,6 +7105,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		try {
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					await this.#assertFence(tx, fence, "updateThread");
 					const [rows] = await tx.run({
 						sql: `SELECT * FROM ${tableThreads} WHERE id = @id LIMIT 1`,
 						params: { id },
@@ -7430,8 +7572,9 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		}
 	}
 	/** Upserts a batch of messages and bumps every touched thread's `updatedAt` in a single transaction. */
-	async saveMessages({ messages }) {
+	async saveMessages({ messages, fence: explicitFence }) {
 		if (messages.length === 0) return { messages: [] };
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence);
 		const threadIds = /* @__PURE__ */ new Set();
 		for (const message of messages) {
 			if (!message.threadId) throw new _mastra_core_error.MastraError({
@@ -7457,6 +7600,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		try {
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					await this.#assertFence(tx, fence, "saveMessages");
 					for (const message of messages) {
 						if (!message.resourceId) throw new Error("Expected to find a resourceId for message");
 						const sql = `INSERT OR UPDATE INTO ${tableMessages} (id, ${quoteIdent("thread_id", "column name")}, content, ${quoteIdent("createdAt", "column name")}, role, type, ${quoteIdent("resourceId", "column name")})
@@ -7494,6 +7638,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 			}));
 			return { messages: new _mastra_core_agent.MessageList().add(messages, "memory").get.all.db() };
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "SAVE_MESSAGES", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -7503,8 +7648,9 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		}
 	}
 	/** Merges partial updates onto existing messages and bumps affected thread `updatedAt`. */
-	async updateMessages({ messages }) {
+	async updateMessages({ messages, fence: explicitFence }) {
 		if (!messages || messages.length === 0) return [];
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence);
 		const messageIds = messages.map((m) => m.id);
 		const params = {};
 		const placeholders = messageIds.map((id, i) => {
@@ -7522,6 +7668,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		try {
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					await this.#assertFence(tx, fence, "updateMessages");
 					const [existingRows] = await tx.run({
 						sql: selectSql,
 						params,
@@ -7597,6 +7744,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 				}
 			}));
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "UPDATE_MESSAGES", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -7620,8 +7768,9 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		});
 	}
 	/** Deletes a batch of messages and bumps the affected threads' `updatedAt`. */
-	async deleteMessages(messageIds) {
+	async deleteMessages(messageIds, options) {
 		if (!messageIds || messageIds.length === 0) return;
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, options?.fence);
 		try {
 			const messageTableName = quoteIdent(_mastra_core_storage.TABLE_MESSAGES, "table name");
 			const threadTableName = quoteIdent(_mastra_core_storage.TABLE_THREADS, "table name");
@@ -7639,6 +7788,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 			const threadIds = threadRows.map((r) => r.thread_id).filter(Boolean);
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					await this.#assertFence(tx, fence, "deleteMessages");
 					await tx.runUpdate({
 						sql: `DELETE FROM ${messageTableName} WHERE id IN (${placeholders})`,
 						params
@@ -7656,6 +7806,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 				}
 			}));
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "DELETE_MESSAGES", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -7714,13 +7865,15 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 		return resource;
 	}
 	/** Updates a resource's `workingMemory` and merges its `metadata`. */
-	async updateResource({ resourceId, workingMemory, metadata }) {
+	async updateResource({ resourceId, workingMemory, metadata, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence);
 		const tableResources = quoteIdent(_mastra_core_storage.TABLE_RESOURCES, "table name");
 		const now = /* @__PURE__ */ new Date();
 		let updated = null;
 		try {
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					await this.#assertFence(tx, fence, "updateResource");
 					const [rows] = await tx.run({
 						sql: `SELECT * FROM ${tableResources} WHERE id = @id LIMIT 1`,
 						params: { id: resourceId },
@@ -7784,6 +7937,7 @@ var MemorySpanner = class MemorySpanner extends _mastra_core_storage.MemoryStora
 			}));
 			return updated;
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			const mastraError = new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "UPDATE_RESOURCE", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -12291,6 +12445,30 @@ var WorkflowDefinitionsSpanner = class WorkflowDefinitionsSpanner extends _mastr
 };
 //#endregion
 //#region src/storage/domains/workflows/index.ts
+const RUN_OWNERS_TABLE = quoteIdent(_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS, "table name");
+const RUN_ID = quoteIdent("runId", "column name");
+const OWNER_ID = quoteIdent("ownerId", "column name");
+const LEASE_EXPIRES_AT = quoteIdent("leaseExpiresAt", "column name");
+const UPDATED_AT = quoteIdent("updatedAt", "column name");
+/** Reads a run's ownership record, judging the lease against the database clock. */
+async function readRunOwner(q, runId) {
+	const [rows] = await q.run({
+		sql: `SELECT generation, ${OWNER_ID} AS ownerId, ${LEASE_EXPIRES_AT} AS leaseExpiresAt, ${DB_NOW_MS} AS nowMs
+          FROM ${RUN_OWNERS_TABLE} WHERE ${RUN_ID} = @runId`,
+		params: { runId },
+		json: true
+	});
+	const row = rows[0];
+	if (!row) return null;
+	const leaseExpiresAt = row.leaseExpiresAt === null ? null : Number(row.leaseExpiresAt);
+	return {
+		runId,
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId),
+		leaseExpiresAt: leaseExpiresAt === null ? null : new Date(leaseExpiresAt),
+		live: leaseExpiresAt !== null && leaseExpiresAt > Number(row.nowMs)
+	};
+}
 /**
 * Spanner-backed storage for workflow run snapshots, including persistence,
 * incremental updates, and listing of historical runs.
@@ -12371,12 +12549,19 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		const indexes = this.getDefaultIndexDefinitions().filter((idx) => hasStatus || !idx.columns.some((c) => c.startsWith("snapshotStatus")));
 		await this.db.createIndexes(indexes);
 	}
-	/** Creates the workflow snapshot table, the snapshotStatus generated column, and indexes. */
+	/**
+	* Creates the workflow snapshot and run ownership tables, the snapshotStatus
+	* generated column, and indexes.
+	*/
 	async init() {
 		await this.db.createTable({
 			tableName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
 			schema: _mastra_core_storage.TABLE_SCHEMAS[_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT]
 		});
+		await this.db.createTable({
+			tableName: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS]
+		});
 		await this.ensureStatusColumn();
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
@@ -12425,9 +12610,121 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		if (!this.indexes || this.indexes.length === 0) return;
 		await this.db.createIndexes(this.indexes);
 	}
-	/** Removes every workflow snapshot row. Intended for tests. */
+	/** Removes every workflow snapshot and run ownership row. Intended for tests. */
 	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 });
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	#ownershipError(operation, runId, error) {
+		return new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", operation, "FAILED"),
+			domain: _mastra_core_error.ErrorDomain.STORAGE,
+			category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+			details: { runId }
+		}, error);
+	}
+	async claimRunOwnership({ runId, ownerId, leaseMs, force, expectedGeneration }) {
+		try {
+			return await inTransaction(this.db, async (tx) => {
+				const existing = await readRunOwner(tx, runId);
+				if (!existing) {
+					if (expectedGeneration !== void 0 && expectedGeneration !== 0) return {
+						acquired: false,
+						record: null
+					};
+					await tx.runUpdate({
+						sql: `INSERT INTO ${RUN_OWNERS_TABLE} (${RUN_ID}, generation, ${OWNER_ID}, ${LEASE_EXPIRES_AT}, ${UPDATED_AT})
+                  VALUES (@runId, ${DB_NOW_MS}, @ownerId, ${DB_NOW_MS} + @leaseMs, ${DB_NOW_MS})`,
+						params: {
+							runId,
+							ownerId,
+							leaseMs
+						}
+					});
+					return {
+						acquired: true,
+						record: await readRunOwner(tx, runId)
+					};
+				}
+				if (!(expectedGeneration === void 0 || existing.generation === expectedGeneration) || !force && existing.live) return {
+					acquired: false,
+					record: existing
+				};
+				await tx.runUpdate({
+					sql: `UPDATE ${RUN_OWNERS_TABLE}
+                SET generation = generation + 1, ${OWNER_ID} = @ownerId, ${LEASE_EXPIRES_AT} = ${DB_NOW_MS} + @leaseMs,
+                    ${UPDATED_AT} = ${DB_NOW_MS}
+                WHERE ${RUN_ID} = @runId`,
+					params: {
+						runId,
+						ownerId,
+						leaseMs
+					}
+				});
+				return {
+					acquired: true,
+					record: await readRunOwner(tx, runId)
+				};
+			});
+		} catch (error) {
+			throw this.#ownershipError("CLAIM_RUN_OWNERSHIP", runId, error);
+		}
+	}
+	async renewRunOwnership({ leaseMs, ...fence }) {
+		try {
+			return await inTransaction(this.db, async (tx) => {
+				const [count] = await tx.runUpdate({
+					sql: `UPDATE ${RUN_OWNERS_TABLE}
+                SET ${LEASE_EXPIRES_AT} = ${DB_NOW_MS} + @leaseMs, ${UPDATED_AT} = ${DB_NOW_MS}
+                WHERE ${RUN_ID} = @runId AND generation = @generation AND ${OWNER_ID} = @ownerId
+                  AND ${LEASE_EXPIRES_AT} IS NOT NULL`,
+					params: {
+						leaseMs,
+						runId: fence.runId,
+						generation: fence.generation,
+						ownerId: fence.ownerId
+					}
+				});
+				const record = await readRunOwner(tx, fence.runId);
+				return count === 1 && record ? {
+					renewed: true,
+					record
+				} : {
+					renewed: false,
+					record
+				};
+			});
+		} catch (error) {
+			throw this.#ownershipError("RENEW_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async releaseRunOwnership(fence) {
+		try {
+			return await inTransaction(this.db, async (tx) => {
+				const [count] = await tx.runUpdate({
+					sql: `UPDATE ${RUN_OWNERS_TABLE} SET ${LEASE_EXPIRES_AT} = NULL, ${UPDATED_AT} = ${DB_NOW_MS}
+                WHERE ${RUN_ID} = @runId AND generation = @generation AND ${OWNER_ID} = @ownerId`,
+					params: {
+						runId: fence.runId,
+						generation: fence.generation,
+						ownerId: fence.ownerId
+					}
+				});
+				return count === 1;
+			});
+		} catch (error) {
+			throw this.#ownershipError("RELEASE_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async getRunOwnership({ runId }) {
+		try {
+			return await readRunOwner(this.database, runId);
+		} catch (error) {
+			throw this.#ownershipError("GET_RUN_OWNERSHIP", runId, error);
+		}
 	}
 	/** Decodes a raw Spanner snapshot row into the public `WorkflowRun` shape. */
 	parseWorkflowRun(row) {
@@ -12451,12 +12748,14 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		};
 	}
 	/** Upserts a workflow run snapshot, preserving the original `createdAt` on update. */
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence, runId);
 		const now = /* @__PURE__ */ new Date();
 		const table = quoteIdent(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "table name");
 		try {
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					if (fence) await assertRunFence(tx, _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS, fence, "persistWorkflowSnapshot");
 					const [rows] = await tx.run({
 						sql: `SELECT ${quoteIdent("createdAt", "column name")}, ${quoteIdent("resourceId", "column name")} FROM ${table}
                     WHERE workflow_name = @workflow_name AND run_id = @run_id`,
@@ -12490,6 +12789,7 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 				}
 			}));
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "PERSIST_WORKFLOW_SNAPSHOT", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -12526,12 +12826,14 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		}
 	}
 	/** Merges a step result and request-context delta into a snapshot inside an RW transaction. */
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence, runId);
 		const table = quoteIdent(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "table name");
 		try {
 			let mergedContext = {};
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				try {
+					if (fence) await assertRunFence(tx, _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS, fence, "updateWorkflowResults");
 					const [rows] = await tx.run({
 						sql: `SELECT snapshot, ${quoteIdent("createdAt", "column name")} FROM ${table}
                     WHERE workflow_name = @workflow_name AND run_id = @run_id`,
@@ -12591,6 +12893,7 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 			}));
 			return mergedContext;
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "UPDATE_WORKFLOW_RESULTS", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -12604,13 +12907,15 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		}
 	}
 	/** Applies a top-level snapshot patch (e.g. status, value) inside an RW transaction. */
-	async updateWorkflowState({ workflowName, runId, opts }) {
+	async updateWorkflowState({ workflowName, runId, opts, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence, runId);
 		const table = quoteIdent(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "table name");
 		try {
 			let updated;
 			await this.db.runWithAbortRetry(() => this.database.runTransactionAsync(async (tx) => {
 				updated = void 0;
 				try {
+					if (fence) await assertRunFence(tx, _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS, fence, "updateWorkflowState");
 					const [rows] = await tx.run({
 						sql: `SELECT snapshot FROM ${table} WHERE workflow_name = @workflow_name AND run_id = @run_id`,
 						params: {
@@ -12721,17 +13026,18 @@ var WorkflowsSpanner = class WorkflowsSpanner extends _mastra_core_storage.Workf
 		}
 	}
 	/** Deletes the snapshot row for a `(workflowName, runId)` pair. */
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
 		const table = quoteIdent(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "table name");
 		try {
-			await this.db.runDml({
+			await withRunFence(this.db, _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS, (0, _mastra_core_storage.resolveRunFence)(this, fence, runId), "deleteWorkflowRunById", (tx) => this.db.runDml({
 				sql: `DELETE FROM ${table} WHERE workflow_name = @workflow_name AND run_id = @run_id`,
 				params: {
 					workflow_name: workflowName,
 					run_id: runId
 				}
-			});
+			}, tx));
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("SPANNER", "DELETE_WORKFLOW_RUN_BY_ID", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,