@mastra/mysql 0.13.1-alpha.0 → 0.13.1

package/dist/index.cjs

@@ -6109,9 +6109,81 @@ function isAppendOnlySince(storedObservations, snapshotObservations) {
 	return stored === snapshot || stored.startsWith(snapshot);
 }
 //#endregion
+//#region src/storage/db/run-fencing.ts
+/**
+* Epoch milliseconds on the database clock. `UTC_TIMESTAMP` is the time the
+* statement started and doesn't depend on the session time zone. Every lease
+* comparison runs in a statement that already holds the run's owner row, so
+* no lock wait sits between that start time and the comparison.
+*/
+const DB_NOW_MS = `(TIMESTAMPDIFF(MICROSECOND, '1970-01-01 00:00:00', UTC_TIMESTAMP(3)) DIV 1000)`;
+const ER_DUP_ENTRY = 1062;
+const ER_LOCK_DEADLOCK = 1213;
+const MAX_CLAIM_ATTEMPTS = 5;
+/**
+* The check half of a fenced write; call it first inside the write's
+* transaction. The shared lock holds the claim row until commit, so a claim
+* that updates the row waits for the write to finish, and every later write
+* sees the new claim.
+*/
+async function assertRunFence(q, claimsTable, fence, operation) {
+	const [rows] = await q.execute(`SELECT generation, ${quoteIdentifier("ownerId", "column name")} AS ownerId FROM ${claimsTable}
+     WHERE ${quoteIdentifier("runId", "column name")} = ? LOCK IN SHARE MODE`, [fence.runId]);
+	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 transaction on its own pooled connection. */
+async function inTransaction(pool, fn) {
+	const connection = await pool.getConnection();
+	try {
+		await connection.beginTransaction();
+		const result = await fn(connection);
+		await connection.commit();
+		return result;
+	} catch (error) {
+		await connection.rollback().catch(() => {});
+		throw error;
+	} finally {
+		connection.release();
+	}
+}
+/**
+* Runs `write` directly when it carries no fence, or in a transaction behind
+* the fence check when it does.
+*/
+function withRunFence(pool, claimsTable, fence, operation, write) {
+	if (!fence) return write(pool);
+	return inTransaction(pool, async (connection) => {
+		await assertRunFence(connection, claimsTable, fence, operation);
+		return write(connection);
+	});
+}
+/**
+* Runs a transaction that creates or updates a run's claim row, retrying when
+* two first claims race to insert it. Under REPEATABLE READ both lock the gap
+* where the row would go and one is chosen as a deadlock victim; under READ
+* COMMITTED the later insert hits the duplicate key. On retry the row exists
+* and the claim serializes behind its row lock.
+*/
+async function claimTransaction(pool, fn) {
+	for (let attempt = 1;; attempt++) try {
+		return await inTransaction(pool, fn);
+	} catch (error) {
+		const errno = error.errno;
+		if (attempt >= MAX_CLAIM_ATTEMPTS || errno !== ER_DUP_ENTRY && errno !== ER_LOCK_DEADLOCK) throw error;
+	}
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 const OM_TABLE = "mastra_observational_memory";
 const OM_TABLE_QUOTED = quoteIdentifier(OM_TABLE, "table name");
+const RUN_FENCES_TABLE = formatTableName(_mastra_core_storage.TABLE_MEMORY_RUN_FENCES);
+const RUN_ID$1 = quoteIdentifier("runId", "column name");
+const OWNER_ID$1 = quoteIdentifier("ownerId", "column name");
+const RETIRED_AT = quoteIdentifier("retiredAt", "column name");
 /** Canonical head order: newest generation, then earliest createdAt, then lowest id. */
 const OM_HEAD_ORDER = `${quoteIdentifier("generationCount", "column name")} DESC, ${quoteIdentifier("createdAt", "column name")} ASC, ${quoteIdentifier("id", "column name")} ASC`;
 /** Max `supersededBy` hops when redirecting a write aimed at a retired record. */
@@ -6218,6 +6290,69 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 		this.#skipDefaultIndexes = skipDefaultIndexes;
 		this.#indexes = indexes?.filter((idx) => MemoryMySQL.MANAGED_TABLES.includes(idx.table));
 	}
+	supportsRunFencing() {
+		return true;
+	}
+	async raiseRunFence(fence) {
+		try {
+			return await claimTransaction(this.pool, async (connection) => {
+				const [rows] = await connection.execute(`SELECT generation, ${OWNER_ID$1} AS ownerId FROM ${RUN_FENCES_TABLE} WHERE ${RUN_ID$1} = ? FOR UPDATE`, [fence.runId]);
+				const row = rows[0];
+				if (!row) {
+					await connection.execute(`INSERT INTO ${RUN_FENCES_TABLE} (${RUN_ID$1}, generation, ${OWNER_ID$1}) VALUES (?, ?, ?)`, [
+						fence.runId,
+						fence.generation,
+						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 connection.execute(`UPDATE ${RUN_FENCES_TABLE} SET generation = ?, ${OWNER_ID$1} = ?, ${RETIRED_AT} = NULL WHERE ${RUN_ID$1} = ?`, [
+					fence.generation,
+					fence.ownerId,
+					fence.runId
+				]);
+				return true;
+			});
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", "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) {
+		try {
+			return await inTransaction(this.pool, async (connection) => {
+				const [rows] = await connection.execute(`SELECT generation, ${OWNER_ID$1} AS ownerId FROM ${RUN_FENCES_TABLE} WHERE ${RUN_ID$1} = ? FOR UPDATE`, [fence.runId]);
+				const row = rows[0];
+				if (!row || Number(row.generation) !== fence.generation || String(row.ownerId) !== fence.ownerId) return false;
+				await connection.execute(`UPDATE ${RUN_FENCES_TABLE} SET ${RETIRED_AT} = ${DB_NOW_MS} WHERE ${RUN_ID$1} = ?`, [fence.runId]);
+				return true;
+			});
+		} catch (error) {
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", "RETIRE_RUN_FENCE", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	/** Runs `write` behind its own fence, otherwise the one in scope for this store. */
+	#fenced(fence, operation, write) {
+		return withRunFence(this.pool, RUN_FENCES_TABLE, (0, _mastra_core_storage.resolveRunFence)(this, fence), operation, write);
+	}
+	/** The fence check for a write that already runs in its own transaction. */
+	async #assertFence(connection, fence, operation) {
+		const resolved = (0, _mastra_core_storage.resolveRunFence)(this, fence);
+		if (resolved) await assertRunFence(connection, RUN_FENCES_TABLE, resolved, operation);
+	}
 	async init() {
 		await this.operations.createTable({
 			tableName: _mastra_core_storage.TABLE_THREADS,
@@ -6231,6 +6366,10 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			tableName: _mastra_core_storage.TABLE_RESOURCES,
 			schema: _mastra_core_storage.TABLE_SCHEMAS[_mastra_core_storage.TABLE_RESOURCES]
 		});
+		await this.operations.createTable({
+			tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_MEMORY_RUN_FENCES]
+		});
 		const omSchema = withObservationalMemoryLifecycleColumns(_mastra_core_storage.OBSERVATIONAL_MEMORY_TABLE_SCHEMA?.[OM_TABLE]);
 		if (omSchema) {
 			await this.operations.createTable({
@@ -6298,6 +6437,10 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			tableName,
 			schema: _mastra_core_storage.TABLE_SCHEMAS[tableName]
 		}));
+		statements.push(generateTableSQL({
+			tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_MEMORY_RUN_FENCES]
+		}));
 		for (const idx of MemoryMySQL.getDefaultIndexDefs()) statements.push(generateIndexSQL(idx));
 		return statements;
 	}
@@ -6316,6 +6459,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 		await this.pool.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_MESSAGES)}`);
 		await this.pool.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_THREADS)}`);
 		await this.pool.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_RESOURCES)}`);
+		await this.pool.execute(`DELETE FROM ${RUN_FENCES_TABLE}`);
 		try {
 			await this.pool.execute(`DELETE FROM ${OM_TABLE_QUOTED}`);
 		} catch (err) {
@@ -6496,8 +6640,8 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 		}
 		return includeMessages;
 	}
-	async upsertThread(thread) {
-		await this.operations.insert({
+	async upsertThread(q, thread) {
+		const statement = prepareStatement({
 			tableName: _mastra_core_storage.TABLE_THREADS,
 			record: {
 				id: thread.id,
@@ -6508,18 +6652,22 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 				updatedAt: thread.updatedAt
 			}
 		});
+		await q.execute(statement.sql, statement.args);
+	}
+	async #readThread(q, threadId, resourceId) {
+		let sql = `SELECT * FROM ${formatTableName(_mastra_core_storage.TABLE_THREADS)} WHERE ${quoteIdentifier("id", "column name")} = ?`;
+		const params = [threadId];
+		if (resourceId !== void 0) {
+			sql += ` AND ${quoteIdentifier("resourceId", "column name")} = ?`;
+			params.push(resourceId);
+		}
+		const [rows] = await q.execute(sql, params);
+		const row = rows[0];
+		return row ? this.mapThread(row) : null;
 	}
 	async getThreadById({ threadId, resourceId }) {
 		try {
-			let sql = `SELECT * FROM ${formatTableName(_mastra_core_storage.TABLE_THREADS)} WHERE ${quoteIdentifier("id", "column name")} = ?`;
-			const params = [threadId];
-			if (resourceId !== void 0) {
-				sql += ` AND ${quoteIdentifier("resourceId", "column name")} = ?`;
-				params.push(resourceId);
-			}
-			const [rows] = await this.pool.execute(sql, params);
-			const row = rows[0];
-			return row ? this.mapThread(row) : null;
+			return await this.#readThread(this.pool, threadId, resourceId);
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_MEMORY_GET_THREAD_BY_ID_FAILED",
@@ -6672,11 +6820,12 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			} : void 0
 		});
 	}
-	async saveThread({ thread }) {
+	async saveThread({ thread, fence }) {
 		try {
-			await this.upsertThread(thread);
+			await this.#fenced(fence, "saveThread", (q) => this.upsertThread(q, thread));
 			return thread;
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_MEMORY_SAVE_THREAD_FAILED",
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -6685,36 +6834,39 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			}, error);
 		}
 	}
-	async updateThread({ id, title, metadata }) {
+	async updateThread({ id, title, metadata, fence }) {
 		try {
-			const existing = await this.getThreadById({ threadId: id });
-			if (!existing) throw new _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", "UPDATE_THREAD", "NOT_FOUND"),
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.ErrorCategory.USER,
-				text: `Thread ${id} not found`,
-				details: { threadId: id }
-			});
-			const mergedMetadata = {
-				...existing.metadata ?? {},
-				...metadata ?? {}
-			};
-			const updatedAt = /* @__PURE__ */ new Date();
-			await this.operations.update({
-				tableName: _mastra_core_storage.TABLE_THREADS,
-				keys: { id },
-				data: {
+			return await this.#fenced(fence, "updateThread", async (q) => {
+				const existing = await this.#readThread(q, id);
+				if (!existing) throw new _mastra_core_error.MastraError({
+					id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", "UPDATE_THREAD", "NOT_FOUND"),
+					domain: _mastra_core_error.ErrorDomain.STORAGE,
+					category: _mastra_core_error.ErrorCategory.USER,
+					text: `Thread ${id} not found`,
+					details: { threadId: id }
+				});
+				const mergedMetadata = {
+					...existing.metadata ?? {},
+					...metadata ?? {}
+				};
+				const updatedAt = /* @__PURE__ */ new Date();
+				const statement = prepareUpdateStatement({
+					tableName: _mastra_core_storage.TABLE_THREADS,
+					keys: { id },
+					updates: {
+						title: title ?? existing.title,
+						metadata: JSON.stringify(mergedMetadata),
+						updatedAt
+					}
+				});
+				await q.execute(statement.sql, statement.args);
+				return {
+					...existing,
 					title: title ?? existing.title,
-					metadata: JSON.stringify(mergedMetadata),
+					metadata: mergedMetadata,
 					updatedAt
-				}
+				};
 			});
-			return {
-				...existing,
-				title: title ?? existing.title,
-				metadata: mergedMetadata,
-				updatedAt
-			};
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -6795,6 +6947,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 		const insertedIds = [];
 		try {
 			await connection.beginTransaction();
+			await this.#assertFence(connection, args.fence, "saveMessages");
 			for (const message of messages) {
 				if (!message.threadId) throw new _mastra_core_error.MastraError({
 					id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", "SAVE_MESSAGES", "INVALID_INPUT"),
@@ -6888,18 +7041,29 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 				if (update.threadId && update.threadId !== current.threadId && current.threadId) affectedThreads.set(current.threadId, now);
 			}
 			if (!updates.length) return existing;
-			await this.operations.batchUpdate({
-				tableName: _mastra_core_storage.TABLE_MESSAGES,
-				items: updates
-			});
-			for (const [threadId, timestamp] of affectedThreads.entries()) await this.operations.update({
-				tableName: _mastra_core_storage.TABLE_THREADS,
-				keys: { id: threadId },
-				data: { updatedAt: timestamp }
+			await inTransaction(this.pool, async (connection) => {
+				await this.#assertFence(connection, args.fence, "updateMessages");
+				for (const { keys, data } of updates) {
+					const statement = prepareUpdateStatement({
+						tableName: _mastra_core_storage.TABLE_MESSAGES,
+						updates: data,
+						keys
+					});
+					await connection.execute(statement.sql, statement.args);
+				}
+				for (const [threadId, timestamp] of affectedThreads.entries()) {
+					const statement = prepareUpdateStatement({
+						tableName: _mastra_core_storage.TABLE_THREADS,
+						updates: { updatedAt: timestamp },
+						keys: { id: threadId }
+					});
+					await connection.execute(statement.sql, statement.args);
+				}
 			});
 			const { messages: updated } = await this.listMessagesById({ messageIds: messages.map((m) => m.id) });
 			return updated;
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_MEMORY_UPDATE_MESSAGES_FAILED",
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -6907,19 +7071,22 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			}, error);
 		}
 	}
-	async deleteMessages(messageIds) {
+	async deleteMessages(messageIds, options) {
 		if (!messageIds.length) return;
 		try {
-			const placeholders = messageIds.map(() => "?").join(", ");
-			const [rows] = await this.pool.execute(`SELECT DISTINCT thread_id FROM ${formatTableName(_mastra_core_storage.TABLE_MESSAGES)} WHERE id IN (${placeholders})`, messageIds);
-			const threadIds = rows.map((row) => row.thread_id).filter((threadId) => Boolean(threadId));
-			await this.pool.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_MESSAGES)} WHERE id IN (${placeholders})`, messageIds);
-			if (threadIds.length) {
-				const threadPlaceholders = threadIds.map(() => "?").join(", ");
-				const timestamp = transformToSqlValue(/* @__PURE__ */ new Date());
-				await this.pool.execute(`UPDATE ${formatTableName(_mastra_core_storage.TABLE_THREADS)} SET ${quoteIdentifier("updatedAt", "column name")} = ? WHERE id IN (${threadPlaceholders})`, [timestamp, ...threadIds]);
-			}
+			await this.#fenced(options?.fence, "deleteMessages", async (q) => {
+				const placeholders = messageIds.map(() => "?").join(", ");
+				const [rows] = await q.execute(`SELECT DISTINCT thread_id FROM ${formatTableName(_mastra_core_storage.TABLE_MESSAGES)} WHERE id IN (${placeholders})`, messageIds);
+				const threadIds = rows.map((row) => row.thread_id).filter((threadId) => Boolean(threadId));
+				await q.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_MESSAGES)} WHERE id IN (${placeholders})`, messageIds);
+				if (threadIds.length) {
+					const threadPlaceholders = threadIds.map(() => "?").join(", ");
+					const timestamp = transformToSqlValue(/* @__PURE__ */ new Date());
+					await q.execute(`UPDATE ${formatTableName(_mastra_core_storage.TABLE_THREADS)} SET ${quoteIdentifier("updatedAt", "column name")} = ? WHERE id IN (${threadPlaceholders})`, [timestamp, ...threadIds]);
+				}
+			});
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_MEMORY_DELETE_MESSAGES_FAILED",
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -7318,19 +7485,23 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			}, error);
 		}
 	}
+	async #insertResource(q, resource) {
+		const metadataValue = resource.metadata === void 0 || resource.metadata === null ? null : JSON.stringify(resource.metadata);
+		const statement = prepareStatement({
+			tableName: _mastra_core_storage.TABLE_RESOURCES,
+			record: {
+				id: resource.id,
+				workingMemory: resource.workingMemory ?? null,
+				metadata: metadataValue,
+				createdAt: resource.createdAt ?? /* @__PURE__ */ new Date(),
+				updatedAt: resource.updatedAt ?? /* @__PURE__ */ new Date()
+			}
+		});
+		await q.execute(statement.sql, statement.args);
+	}
 	async saveResource({ resource }) {
 		try {
-			const metadataValue = resource.metadata === void 0 || resource.metadata === null ? null : JSON.stringify(resource.metadata);
-			await this.operations.insert({
-				tableName: _mastra_core_storage.TABLE_RESOURCES,
-				record: {
-					id: resource.id,
-					workingMemory: resource.workingMemory ?? null,
-					metadata: metadataValue,
-					createdAt: resource.createdAt ?? /* @__PURE__ */ new Date(),
-					updatedAt: resource.updatedAt ?? /* @__PURE__ */ new Date()
-				}
-			});
+			await this.#insertResource(this.pool, resource);
 			return resource;
 		} catch (error) {
 			throw new _mastra_core_error.MastraError({
@@ -7341,7 +7512,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 			}, error);
 		}
 	}
-	async updateResource({ resourceId, workingMemory, metadata }) {
+	async updateResource({ resourceId, workingMemory, metadata, fence }) {
 		try {
 			const existing = await this.getResourceById({ resourceId });
 			if (!existing) {
@@ -7352,22 +7523,24 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 					createdAt: /* @__PURE__ */ new Date(),
 					updatedAt: /* @__PURE__ */ new Date()
 				};
-				return await this.saveResource({ resource: newResource });
+				await this.#fenced(fence, "updateResource", (q) => this.#insertResource(q, newResource));
+				return newResource;
 			}
 			const mergedMetadata = metadata !== void 0 ? {
 				...existing.metadata ?? {},
 				...metadata ?? {}
 			} : existing.metadata;
 			const metadataValue = metadata !== void 0 ? metadata === null ? null : JSON.stringify(mergedMetadata ?? {}) : void 0;
-			await this.operations.update({
+			const statement = prepareUpdateStatement({
 				tableName: _mastra_core_storage.TABLE_RESOURCES,
 				keys: { id: resourceId },
-				data: {
+				updates: {
 					...workingMemory !== void 0 ? { workingMemory } : {},
 					...metadataValue !== void 0 ? { metadata: metadataValue } : {},
 					updatedAt: /* @__PURE__ */ new Date()
 				}
 			});
+			await this.#fenced(fence, "updateResource", (q) => q.execute(statement.sql, statement.args));
 			const updated = await this.getResourceById({ resourceId });
 			if (!updated) throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", "UPDATE_RESOURCE", "NOT_FOUND_AFTER_UPDATE"),
@@ -7572,7 +7745,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 					input.id
 				]);
 				return { applied: true };
-			});
+			}, "commitActiveObservations");
 		} catch (error) {
 			rethrowOrWrapOM(error, input.id, "UPDATE_ACTIVE_OBSERVATIONS");
 		}
@@ -7595,11 +7768,95 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 				});
 				if (!plan) return stored;
 				return this.rollOverOMRow(connection, stored.id, plan.observations, plan.tokenCount, input.newRecordId, false);
-			});
+			}, "createReflectionGeneration");
 		} catch (error) {
 			rethrowOrWrapOM(error, input.currentRecord.id, "CREATE_REFLECTION_GENERATION", { currentRecordId: input.currentRecord.id });
 		}
 	}
+	async #insertReflectionGeneration(q, input) {
+		const id = globalThis.crypto.randomUUID();
+		const now = /* @__PURE__ */ new Date();
+		const lookupKey = this.getOMKey(input.currentRecord.threadId, input.currentRecord.resourceId);
+		const record = {
+			id,
+			scope: input.currentRecord.scope,
+			threadId: input.currentRecord.threadId,
+			resourceId: input.currentRecord.resourceId,
+			createdAt: now,
+			updatedAt: now,
+			lastObservedAt: input.currentRecord.lastObservedAt,
+			originType: "reflection",
+			generationCount: input.currentRecord.generationCount + 1,
+			activeObservations: input.reflection,
+			totalTokensObserved: input.currentRecord.totalTokensObserved,
+			observationTokenCount: input.tokenCount,
+			pendingMessageTokens: 0,
+			isReflecting: false,
+			isObserving: false,
+			isBufferingObservation: false,
+			isBufferingReflection: false,
+			lastBufferedAtTokens: 0,
+			lastBufferedAtTime: null,
+			config: input.currentRecord.config,
+			metadata: input.currentRecord.metadata,
+			observedTimezone: input.currentRecord.observedTimezone
+		};
+		const nowSql = transformToSqlValue(now);
+		const cols = [
+			"id",
+			"lookupKey",
+			"scope",
+			"resourceId",
+			"threadId",
+			"activeObservations",
+			"activeObservationsPendingUpdate",
+			"originType",
+			"config",
+			"generationCount",
+			"lastObservedAt",
+			"lastReflectionAt",
+			"pendingMessageTokens",
+			"totalTokensObserved",
+			"observationTokenCount",
+			"isObserving",
+			"isReflecting",
+			"isBufferingObservation",
+			"isBufferingReflection",
+			"lastBufferedAtTokens",
+			"lastBufferedAtTime",
+			"observedTimezone",
+			"createdAt",
+			"updatedAt"
+		].map(omCol).join(", ");
+		const placeholders = Array.from({ length: 24 }, () => "?").join(", ");
+		await q.execute(`INSERT INTO ${OM_TABLE_QUOTED} (${cols}) VALUES (${placeholders})`, [
+			id,
+			lookupKey,
+			record.scope,
+			record.resourceId,
+			record.threadId || null,
+			input.reflection,
+			null,
+			"reflection",
+			JSON.stringify(record.config),
+			input.currentRecord.generationCount + 1,
+			record.lastObservedAt ? transformToSqlValue(record.lastObservedAt) : null,
+			nowSql,
+			record.pendingMessageTokens,
+			record.totalTokensObserved,
+			record.observationTokenCount,
+			false,
+			false,
+			false,
+			false,
+			0,
+			null,
+			record.observedTimezone || null,
+			nowSql,
+			nowSql
+		]);
+		return record;
+	}
 	async setReflectingFlag(id, isReflecting) {
 		await this.updateOMFlag(id, "isReflecting", isReflecting, "SET_REFLECTING_FLAG");
 	}
@@ -7705,7 +7962,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 					persisted: true,
 					recordId: target.id
 				};
-			});
+			}, "appendBufferedObservations");
 		} catch (error) {
 			rethrowOrWrapOM(error, input.id, "UPDATE_BUFFERED_OBSERVATIONS");
 		}
@@ -7817,7 +8074,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 					suggestedContinuation: latestChunkHints?.suggestedContinuation ?? void 0,
 					currentTask: latestChunkHints?.currentTask ?? void 0
 				};
-			});
+			}, "swapBufferedToActive");
 		} catch (error) {
 			rethrowOrWrapOM(error, input.id, "SWAP_BUFFERED_TO_ACTIVE");
 		}
@@ -7826,7 +8083,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 		try {
 			const nowSql = transformToSqlValue(/* @__PURE__ */ new Date());
 			const br = omCol("bufferedReflection");
-			const [result] = await this.pool.execute(`UPDATE ${OM_TABLE_QUOTED} SET
+			const [result] = await this.#fenced(void 0, "updateBufferedReflection", (q) => q.execute(`UPDATE ${OM_TABLE_QUOTED} SET
           ${br} = CASE
             WHEN ${br} IS NOT NULL AND ${br} != ''
             THEN CONCAT(${br}, CHAR(10), CHAR(10), ?)
@@ -7844,7 +8101,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 				input.reflectedObservationLineCount,
 				nowSql,
 				input.id
-			]);
+			]));
 			if (result.affectedRows === 0) throwOMNotFound(input.id, "UPDATE_BUFFERED_REFLECTION");
 		} catch (error) {
 			rethrowOrWrapOM(error, input.id, "UPDATE_BUFFERED_REFLECTION");
@@ -7872,7 +8129,7 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 				const newObservations = unreflectedContent ? `${bufferedReflection}\n\n${unreflectedContent}` : bufferedReflection;
 				const tokenCount = input.tokenCount + Math.max(0, (stored.observationTokenCount ?? 0) - (currentRecord.observationTokenCount ?? 0));
 				return this.rollOverOMRow(connection, stored.id, newObservations, tokenCount, input.newRecordId, true);
-			});
+			}, "swapBufferedReflectionToActive");
 		} catch (error) {
 			rethrowOrWrapOM(error, input.currentRecord.id, "SWAP_BUFFERED_REFLECTION_TO_ACTIVE");
 		}
@@ -7883,11 +8140,12 @@ var MemoryMySQL = class MemoryMySQL extends _mastra_core_storage.MemoryStorage {
 	* only expected lock conflict is a wait; a deadlock or lock-wait timeout (e.g. against the
 	* startup backfill's scan) is retried a bounded number of times.
 	*/
-	async withOMTransaction(fn) {
+	async withOMTransaction(fn, fencedOperation) {
 		for (let attempt = 1;; attempt++) {
 			const connection = await this.pool.getConnection();
 			try {
 				await connection.beginTransaction();
+				if (fencedOperation) await this.#assertFence(connection, void 0, fencedOperation);
 				const result = await fn(connection);
 				await connection.commit();
 				return result;
@@ -11064,6 +11322,26 @@ function parseSnapshot(snapshot) {
 	}
 	return snapshot;
 }
+const RUN_OWNERS_TABLE = formatTableName(_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS);
+const RUN_ID = quoteIdentifier("runId", "column name");
+const OWNER_ID = quoteIdentifier("ownerId", "column name");
+const LEASE_EXPIRES_AT = quoteIdentifier("leaseExpiresAt", "column name");
+const UPDATED_AT = quoteIdentifier("updatedAt", "column name");
+const RUN_OWNER_COLUMNS = `generation, ${OWNER_ID} AS ownerId, ${LEASE_EXPIRES_AT} AS leaseExpiresAt, ${DB_NOW_MS} AS nowMs`;
+function toRunOwnershipRecord(runId, row) {
+	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)
+	};
+}
+async function readRunOwner(q, runId) {
+	const [rows] = await q.execute(`SELECT ${RUN_OWNER_COLUMNS} FROM ${RUN_OWNERS_TABLE} WHERE ${RUN_ID} = ?`, [runId]);
+	return rows[0] ? toRunOwnershipRecord(runId, rows[0]) : null;
+}
 function mapWorkflowRow(row) {
 	return {
 		workflowName: row.workflow_name,
@@ -11096,6 +11374,9 @@ var WorkflowsMySQL = class WorkflowsMySQL extends _mastra_core_storage.Workflows
 			tableName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
 			schema: _mastra_core_storage.TABLE_SCHEMAS[_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT],
 			compositePrimaryKey: ["workflow_name", "run_id"]
+		}), generateTableSQL({
+			tableName: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS]
 		})];
 	}
 	constructor({ operations, pool, skipDefaultIndexes, indexes }) {
@@ -11139,16 +11420,125 @@ var WorkflowsMySQL = class WorkflowsMySQL extends _mastra_core_storage.Workflows
 			schema,
 			ifNotExists: ["resourceId"]
 		});
+		await this.operations.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.createDefaultIndexes();
 		await this.createCustomIndexes();
 	}
 	async dangerouslyClearAll() {
 		await this.pool.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT)}`);
+		await this.pool.execute(`DELETE FROM ${RUN_OWNERS_TABLE}`);
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	#ownershipError(operation, runId, error) {
+		return new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createStorageErrorId)("MYSQL", 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 claimTransaction(this.pool, async (connection) => {
+				const [existing] = await connection.execute(`SELECT generation FROM ${RUN_OWNERS_TABLE} WHERE ${RUN_ID} = ? FOR UPDATE`, [runId]);
+				if (existing.length === 0) {
+					if (expectedGeneration !== void 0 && expectedGeneration !== 0) return {
+						acquired: false,
+						record: null
+					};
+					await connection.execute(`INSERT INTO ${RUN_OWNERS_TABLE} (${RUN_ID}, generation, ${OWNER_ID}, ${LEASE_EXPIRES_AT}, ${UPDATED_AT})
+             VALUES (?, GREATEST(1, ${DB_NOW_MS}), ?, ${DB_NOW_MS} + ?, ${DB_NOW_MS})`, [
+						runId,
+						ownerId,
+						leaseMs
+					]);
+					return {
+						acquired: true,
+						record: await readRunOwner(connection, runId)
+					};
+				}
+				await connection.execute(`UPDATE ${RUN_OWNERS_TABLE}
+           SET generation = generation + 1, ${OWNER_ID} = ?, ${LEASE_EXPIRES_AT} = ${DB_NOW_MS} + ?,
+               ${UPDATED_AT} = ${DB_NOW_MS}
+           WHERE ${RUN_ID} = ?
+             AND (? IS NULL OR generation = ?)
+             AND (? OR ${LEASE_EXPIRES_AT} IS NULL OR ${LEASE_EXPIRES_AT} <= ${DB_NOW_MS})`, [
+					ownerId,
+					leaseMs,
+					runId,
+					expectedGeneration ?? null,
+					expectedGeneration ?? null,
+					force === true
+				]);
+				const record = await readRunOwner(connection, runId);
+				return record && record.generation === Number(existing[0].generation) + 1 ? {
+					acquired: true,
+					record
+				} : {
+					acquired: false,
+					record
+				};
+			});
+		} catch (error) {
+			throw this.#ownershipError("CLAIM_RUN_OWNERSHIP", runId, error);
+		}
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async renewRunOwnership({ leaseMs, ...fence }) {
 		try {
-			await this.pool.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT)} WHERE ${quoteIdentifier("workflow_name", "column name")} = ? AND ${quoteIdentifier("run_id", "column name")} = ?`, [workflowName, runId]);
+			return await inTransaction(this.pool, async (connection) => {
+				await connection.execute(`UPDATE ${RUN_OWNERS_TABLE}
+           SET ${LEASE_EXPIRES_AT} = ${DB_NOW_MS} + ?, ${UPDATED_AT} = ${DB_NOW_MS}
+           WHERE ${RUN_ID} = ? AND generation = ? AND ${OWNER_ID} = ? AND ${LEASE_EXPIRES_AT} IS NOT NULL`, [
+					leaseMs,
+					fence.runId,
+					fence.generation,
+					fence.ownerId
+				]);
+				const record = await readRunOwner(connection, fence.runId);
+				return record && (0, _mastra_core_storage.matchesRunFence)(record, fence) && record.leaseExpiresAt !== null ? {
+					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.pool, async (connection) => {
+				await connection.execute(`UPDATE ${RUN_OWNERS_TABLE} SET ${LEASE_EXPIRES_AT} = NULL, ${UPDATED_AT} = ${DB_NOW_MS}
+           WHERE ${RUN_ID} = ? AND generation = ? AND ${OWNER_ID} = ?`, [
+					fence.runId,
+					fence.generation,
+					fence.ownerId
+				]);
+				return (0, _mastra_core_storage.matchesRunFence)(await readRunOwner(connection, fence.runId), fence);
+			});
+		} catch (error) {
+			throw this.#ownershipError("RELEASE_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async getRunOwnership({ runId }) {
+		try {
+			return await readRunOwner(this.pool, runId);
+		} catch (error) {
+			throw this.#ownershipError("GET_RUN_OWNERSHIP", runId, error);
+		}
+	}
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
+		try {
+			await withRunFence(this.pool, RUN_OWNERS_TABLE, (0, _mastra_core_storage.resolveRunFence)(this, fence, runId), "deleteWorkflowRunById", (q) => q.execute(`DELETE FROM ${formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT)} WHERE ${quoteIdentifier("workflow_name", "column name")} = ? AND ${quoteIdentifier("run_id", "column name")} = ?`, [workflowName, runId]));
+		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_WORKFLOWS_DELETE_RUN_BY_ID_FAILED",
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -11160,10 +11550,12 @@ var WorkflowsMySQL = class WorkflowsMySQL extends _mastra_core_storage.Workflows
 			}, error);
 		}
 	}
-	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 connection = await this.pool.getConnection();
 		try {
 			await connection.beginTransaction();
+			if (fence) await assertRunFence(connection, RUN_OWNERS_TABLE, fence, "updateWorkflowResults");
 			const [rows] = await connection.execute(`SELECT snapshot FROM ${formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT)} WHERE ${quoteIdentifier("workflow_name", "column name")} = ? AND ${quoteIdentifier("run_id", "column name")} = ? FOR UPDATE`, [workflowName, runId]);
 			if (!Array.isArray(rows) || rows.length === 0) {
 				await connection.rollback();
@@ -11214,10 +11606,12 @@ var WorkflowsMySQL = class WorkflowsMySQL extends _mastra_core_storage.Workflows
 			connection.release();
 		}
 	}
-	async updateWorkflowState({ workflowName, runId, opts }) {
+	async updateWorkflowState({ workflowName, runId, opts, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence, runId);
 		const connection = await this.pool.getConnection();
 		try {
 			await connection.beginTransaction();
+			if (fence) await assertRunFence(connection, RUN_OWNERS_TABLE, fence, "updateWorkflowState");
 			const [rows] = await connection.execute(`SELECT snapshot FROM ${formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT)} WHERE ${quoteIdentifier("workflow_name", "column name")} = ? AND ${quoteIdentifier("run_id", "column name")} = ? FOR UPDATE`, [workflowName, runId]);
 			if (!Array.isArray(rows) || rows.length === 0) {
 				await connection.rollback();
@@ -11243,6 +11637,7 @@ var WorkflowsMySQL = class WorkflowsMySQL extends _mastra_core_storage.Workflows
 			return updatedSnapshot;
 		} catch (error) {
 			await connection.rollback();
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_WORKFLOWS_UPDATE_STATE_FAILED",
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -11256,35 +11651,38 @@ var WorkflowsMySQL = class WorkflowsMySQL extends _mastra_core_storage.Workflows
 			connection.release();
 		}
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
 		const now = /* @__PURE__ */ new Date();
 		const createdAtValue = createdAt ?? now;
 		const updatedAtValue = updatedAt ?? now;
+		const tableName = formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT);
 		try {
-			const tableName = formatTableName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT);
-			const [updateResult] = await this.pool.execute(`UPDATE ${tableName}
-         SET ${quoteIdentifier("resourceId", "column name")} = ?,
-             ${quoteIdentifier("snapshot", "column name")} = ?,
-             ${quoteIdentifier("updatedAt", "column name")} = ?
-         WHERE ${quoteIdentifier("workflow_name", "column name")} = ? AND ${quoteIdentifier("run_id", "column name")} = ?`, [
-				resourceId ?? null,
-				JSON.stringify(snapshot),
-				transformToSqlValue(updatedAtValue),
-				workflowName,
-				runId
-			]);
-			if (updateResult.affectedRows > 0) return;
-			await this.pool.execute(`INSERT INTO ${tableName} (${quoteIdentifier("workflow_name", "column name")}, ${quoteIdentifier("run_id", "column name")}, ${quoteIdentifier("resourceId", "column name")}, ${quoteIdentifier("snapshot", "column name")}, ${quoteIdentifier("createdAt", "column name")}, ${quoteIdentifier("updatedAt", "column name")})
-         VALUES (?, ?, ?, ?, ?, ?)
-         ON DUPLICATE KEY UPDATE ${quoteIdentifier("resourceId", "column name")} = VALUES(${quoteIdentifier("resourceId", "column name")}), ${quoteIdentifier("snapshot", "column name")} = VALUES(${quoteIdentifier("snapshot", "column name")}), ${quoteIdentifier("updatedAt", "column name")} = VALUES(${quoteIdentifier("updatedAt", "column name")})`, [
-				workflowName,
-				runId,
-				resourceId ?? null,
-				JSON.stringify(snapshot),
-				transformToSqlValue(createdAtValue),
-				transformToSqlValue(updatedAtValue)
-			]);
+			await withRunFence(this.pool, RUN_OWNERS_TABLE, (0, _mastra_core_storage.resolveRunFence)(this, fence, runId), "persistWorkflowSnapshot", async (q) => {
+				const [updateResult] = await q.execute(`UPDATE ${tableName}
+           SET ${quoteIdentifier("resourceId", "column name")} = ?,
+               ${quoteIdentifier("snapshot", "column name")} = ?,
+               ${quoteIdentifier("updatedAt", "column name")} = ?
+           WHERE ${quoteIdentifier("workflow_name", "column name")} = ? AND ${quoteIdentifier("run_id", "column name")} = ?`, [
+					resourceId ?? null,
+					JSON.stringify(snapshot),
+					transformToSqlValue(updatedAtValue),
+					workflowName,
+					runId
+				]);
+				if (updateResult.affectedRows > 0) return;
+				await q.execute(`INSERT INTO ${tableName} (${quoteIdentifier("workflow_name", "column name")}, ${quoteIdentifier("run_id", "column name")}, ${quoteIdentifier("resourceId", "column name")}, ${quoteIdentifier("snapshot", "column name")}, ${quoteIdentifier("createdAt", "column name")}, ${quoteIdentifier("updatedAt", "column name")})
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON DUPLICATE KEY UPDATE ${quoteIdentifier("resourceId", "column name")} = VALUES(${quoteIdentifier("resourceId", "column name")}), ${quoteIdentifier("snapshot", "column name")} = VALUES(${quoteIdentifier("snapshot", "column name")}), ${quoteIdentifier("updatedAt", "column name")} = VALUES(${quoteIdentifier("updatedAt", "column name")})`, [
+					workflowName,
+					runId,
+					resourceId ?? null,
+					JSON.stringify(snapshot),
+					transformToSqlValue(createdAtValue),
+					transformToSqlValue(updatedAtValue)
+				]);
+			});
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: "MYSQL_WORKFLOWS_PERSIST_SNAPSHOT_FAILED",
 				domain: _mastra_core_error.ErrorDomain.STORAGE,