@mastra/mysql 0.13.0-alpha.1 → 0.13.1-alpha.0

package/dist/index.js

@@ -2,6 +2,7 @@ import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
 import { AGENTS_SCHEMA, AGENT_VERSIONS_SCHEMA, AgentsStorage, BackgroundTasksStorage, BlobStore, ChannelsStorage, DATASETS_SCHEMA, DATASET_ITEMS_SCHEMA, DATASET_VERSIONS_SCHEMA, DatasetsStorage, EXPERIMENTS_SCHEMA, EXPERIMENT_RESULTS_SCHEMA, ExperimentsStorage, FAVORITES_SCHEMA, FavoritesStorage, KNOWLEDGE_ACTIVITY_SCHEMA, KNOWLEDGE_MENTIONS_SCHEMA, KNOWLEDGE_NODES_SCHEMA, KNOWLEDGE_RECORDS_SCHEMA, KNOWLEDGE_SEMANTIC_OUTBOX_SCHEMA, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MCP_CLIENTS_SCHEMA, MCP_CLIENT_VERSIONS_SCHEMA, MCP_SERVERS_SCHEMA, MCP_SERVER_VERSIONS_SCHEMA, MastraCompositeStore, MemoryStorage, OBSERVATIONAL_MEMORY_TABLE_SCHEMA, ObservabilityStorage, PROMPT_BLOCKS_SCHEMA, PROMPT_BLOCK_VERSIONS_SCHEMA, PromptBlocksStorage, SCORERS_SCHEMA, SCORER_DEFINITIONS_SCHEMA, SCORER_DEFINITION_VERSIONS_SCHEMA, SKILLS_SCHEMA, SKILL_BLOBS_SCHEMA, SKILL_VERSIONS_SCHEMA, SPAN_SCHEMA, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, StoreOperations, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_CONFIGS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TOOL_PROVIDER_CONNECTIONS_SCHEMA, ToolProviderConnectionsStorage, TraceStatus, WORKFLOW_DEFINITIONS_SCHEMA, WORKSPACES_SCHEMA, WORKSPACE_VERSIONS_SCHEMA, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, executeRetentionPrune, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, matchesExpectedWorkflowStatus, normalizePerPage, normalizeScheduleTarget, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRetentionTargets, retentionCutoffMs, toTraceSpans, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { createPool } from "mysql2/promise";
 import { parseSqlIdentifier } from "@mastra/core/utils";
+import { createHash } from "crypto";
 import { MessageList } from "@mastra/core/agent";
 import { skillSnapshotFieldValuesEqual } from "@mastra/core/storage/domains/skills";
 //#region src/storage/db/schema-snapshot.ts
@@ -6021,9 +6022,108 @@ var MCPServersMySQL = class MCPServersMySQL extends MCPServersStorage {
 	}
 };
 //#endregion
+//#region ../../packages/_internal-core/dist/memory/index.js
+/**
+* Shared rules for observational memory lifecycle writes. Every storage adapter applies
+* these inside its own atomic section (lock, transaction, or conditional update), so the
+* decisions are identical across adapters.
+*/
+/**
+* Observational memory columns that lifecycle writes depend on. Storage adapters merge these
+* into the table schema they get from `@mastra/core`, so the columns exist even when the
+* installed core predates them.
+*/
+const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS = { supersededBy: {
+	type: "text",
+	nullable: true
+} };
+/** `schema` plus {@link OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS}; `undefined` when `schema` is. */
+function withObservationalMemoryLifecycleColumns(schema) {
+	return schema ? {
+		...schema,
+		...OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS
+	} : void 0;
+}
+/**
+* A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
+* (every message it observed is already at or before the cursor) iff
+* `cursor >= chunk.lastObservedAt - 1ms`.
+*/
+function isBufferedChunkCoveredByCursor(chunkLastObservedAt, cursor) {
+	if (!cursor) return false;
+	return new Date(cursor).getTime() >= new Date(chunkLastObservedAt).getTime() - 1;
+}
+/** The later of two cursors; `undefined` only when both are absent. */
+function maxObservationCursor(a, b) {
+	if (!a) return b ? new Date(b) : void 0;
+	if (!b) return new Date(a);
+	return new Date(Math.max(new Date(a).getTime(), new Date(b).getTime()));
+}
+/**
+* Decide the new generation's text when a reflection built from `snapshot` commits against
+* the stored record.
+*
+* - Stored text equals the snapshot: the reflection replaces it.
+* - Stored text extends the snapshot (activation only appends): the appended tail is kept
+*   after the reflection, and its tokens are added.
+* - Anything else (a non-append rewrite): `null` — the reflection must not be applied.
+*/
+function planReflectionGenerationText(input) {
+	const stored = input.storedObservations ?? "";
+	const snapshot = input.snapshotObservations ?? "";
+	if (stored === snapshot) return {
+		mode: "equal",
+		observations: input.reflection,
+		tokenCount: input.tokenCount
+	};
+	if (!stored.startsWith(snapshot)) return null;
+	const tail = stored.slice(snapshot.length).trimStart();
+	if (!tail.trim()) return {
+		mode: "equal",
+		observations: input.reflection,
+		tokenCount: input.tokenCount
+	};
+	return {
+		mode: "append",
+		observations: input.reflection ? `${input.reflection}\n\n${tail}` : tail,
+		tokenCount: input.tokenCount + Math.max(0, (input.storedObservationTokenCount ?? 0) - (input.snapshotObservationTokenCount ?? 0))
+	};
+}
+/**
+* Backs `updateActiveObservations` in adapters that implement `commitActiveObservations`.
+* Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
+* write that was not applied throws instead of resolving as if it had committed.
+*/
+function assertActiveObservationsApplied(result, id) {
+	if (result.applied) return;
+	throw new Error(result.reason === "retired" ? `Observational memory record ${id} was superseded by a newer generation; observations were not written` : `Observational memory record ${id} changed since the observations were composed; observations were not written`);
+}
+/**
+* Whether the stored text can still accept a reflection built from `snapshot`
+* (equal, or only appended to since).
+*/
+function isAppendOnlySince(storedObservations, snapshotObservations) {
+	const stored = storedObservations ?? "";
+	const snapshot = snapshotObservations ?? "";
+	return stored === snapshot || stored.startsWith(snapshot);
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 const OM_TABLE = "mastra_observational_memory";
 const OM_TABLE_QUOTED = quoteIdentifier(OM_TABLE, "table 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. */
+const OM_MAX_HEAD_HOPS = 3;
+/** Attempts for an OM transaction that hits a deadlock or lock-wait timeout. */
+const OM_MAX_TRANSACTION_ATTEMPTS = 3;
+/** How long initialization waits for the per-key `GET_LOCK` before failing. */
+const OM_INIT_LOCK_TIMEOUT_SECONDS = 30;
+/** ER_LOCK_DEADLOCK (1213) or ER_LOCK_WAIT_TIMEOUT (1205): the transaction was rolled back and can be retried. */
+function isRetryableLockError(error) {
+	const errno = error?.errno;
+	return errno === 1213 || errno === 1205;
+}
 function emitValidationError(message) {
 	return new MastraError({
 		id: "MYSQL_MEMORY_VALIDATION_ERROR",
@@ -6130,7 +6230,7 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 			tableName: TABLE_RESOURCES,
 			schema: TABLE_SCHEMAS[TABLE_RESOURCES]
 		});
-		const omSchema = OBSERVATIONAL_MEMORY_TABLE_SCHEMA?.[OM_TABLE];
+		const omSchema = withObservationalMemoryLifecycleColumns(OBSERVATIONAL_MEMORY_TABLE_SCHEMA?.[OM_TABLE]);
 		if (omSchema) {
 			await this.operations.createTable({
 				tableName: OM_TABLE,
@@ -6153,7 +6253,8 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 					"isBufferingObservation",
 					"isBufferingReflection",
 					"lastBufferedAtTokens",
-					"lastBufferedAtTime"
+					"lastBufferedAtTime",
+					"supersededBy"
 				]
 			});
 		}
@@ -6171,6 +6272,7 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 				if (err?.errno !== 1061) throw err;
 			}
 		}
+		if (omSchema) await this.backfillSupersededBy();
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
 	}
@@ -7287,7 +7389,7 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 	async getObservationalMemory(threadId, resourceId) {
 		try {
 			const lookupKey = this.getOMKey(threadId, resourceId);
-			const [rows] = await this.pool.execute(`SELECT * FROM ${OM_TABLE_QUOTED} WHERE ${omCol("lookupKey")} = ? ORDER BY ${omCol("generationCount")} DESC LIMIT 1`, [lookupKey]);
+			const [rows] = await this.pool.execute(`SELECT * FROM ${OM_TABLE_QUOTED} WHERE ${omCol("lookupKey")} = ? ORDER BY ${OM_HEAD_ORDER} LIMIT 1`, [lookupKey]);
 			if (!rows || rows.length === 0) return null;
 			return this.parseOMRow(rows[0]);
 		} catch (error) {
@@ -7349,32 +7451,11 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 	}
 	async initializeObservationalMemory(input) {
 		try {
+			const lookupKey = this.getOMKey(input.threadId, input.resourceId);
 			const id = globalThis.crypto.randomUUID();
 			const now = /* @__PURE__ */ new Date();
-			const lookupKey = this.getOMKey(input.threadId, input.resourceId);
-			const record = {
-				id,
-				scope: input.scope,
-				threadId: input.threadId,
-				resourceId: input.resourceId,
-				createdAt: now,
-				updatedAt: now,
-				lastObservedAt: void 0,
-				originType: "initial",
-				generationCount: 0,
-				activeObservations: "",
-				totalTokensObserved: 0,
-				observationTokenCount: 0,
-				pendingMessageTokens: 0,
-				isReflecting: false,
-				isObserving: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				config: input.config,
-				observedTimezone: input.observedTimezone
-			};
+			const existing = await this.getObservationalMemory(input.threadId, input.resourceId);
+			if (existing) return existing;
 			const nowSql = transformToSqlValue(now);
 			const cols = [
 				"id",
@@ -7400,36 +7481,53 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 				"lastBufferedAtTime",
 				"observedTimezone",
 				"createdAt",
-				"updatedAt"
+				"updatedAt",
+				"supersededBy"
 			].map(omCol).join(", ");
-			const placeholders = Array.from({ length: 24 }, () => "?").join(", ");
-			await this.pool.execute(`INSERT INTO ${OM_TABLE_QUOTED} (${cols}) VALUES (${placeholders})`, [
-				id,
-				lookupKey,
-				input.scope,
-				input.resourceId,
-				input.threadId || null,
-				"",
-				null,
-				"initial",
-				JSON.stringify(input.config),
-				0,
-				null,
-				null,
-				0,
-				0,
-				0,
-				false,
-				false,
-				false,
-				false,
-				0,
-				null,
-				input.observedTimezone || null,
-				nowSql,
-				nowSql
-			]);
-			return record;
+			const placeholders = Array.from({ length: 25 }, () => "?").join(", ");
+			const lockName = `mastra_om_init:${createHash("sha256").update(lookupKey).digest("hex").slice(0, 40)}`;
+			const connection = await this.pool.getConnection();
+			try {
+				const [lockRows] = await connection.query("SELECT GET_LOCK(?, ?) AS acquired", [lockName, OM_INIT_LOCK_TIMEOUT_SECONDS]);
+				if (Number(lockRows[0]?.acquired) !== 1) throw new Error(`Timed out waiting for the observational memory initialization lock for ${lookupKey}`);
+				try {
+					const [liveRows] = await connection.query(`SELECT 1 FROM ${OM_TABLE_QUOTED} WHERE ${omCol("lookupKey")} = ? AND ${omCol("supersededBy")} IS NULL LIMIT 1`, [lookupKey]);
+					if (liveRows.length === 0) await connection.execute(`INSERT INTO ${OM_TABLE_QUOTED} (${cols}) VALUES (${placeholders})`, [
+						id,
+						lookupKey,
+						input.scope,
+						input.resourceId,
+						input.threadId || null,
+						"",
+						null,
+						"initial",
+						JSON.stringify(input.config),
+						0,
+						null,
+						null,
+						0,
+						0,
+						0,
+						false,
+						false,
+						false,
+						false,
+						0,
+						null,
+						input.observedTimezone || null,
+						nowSql,
+						nowSql,
+						null
+					]);
+				} finally {
+					await connection.query("SELECT RELEASE_LOCK(?)", [lockName]);
+				}
+			} finally {
+				connection.release();
+			}
+			const head = await this.getObservationalMemory(input.threadId, input.resourceId);
+			if (!head) throwOMNotFound(id, "INITIALIZE_OBSERVATIONAL_MEMORY");
+			return head;
 		} catch (error) {
 			rethrowOrWrapOM(error, "", "INITIALIZE_OBSERVATIONAL_MEMORY", {
 				threadId: input.threadId,
@@ -7438,115 +7536,65 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 		}
 	}
 	async updateActiveObservations(input) {
+		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
+	}
+	async commitActiveObservations(input) {
 		try {
-			const now = /* @__PURE__ */ new Date();
 			const observedMessageIdsJson = input.observedMessageIds ? JSON.stringify(input.observedMessageIds) : null;
-			const [result] = await this.pool.execute(`UPDATE ${OM_TABLE_QUOTED} SET
-          ${omCol("activeObservations")} = ?,
-          ${omCol("lastObservedAt")} = ?,
-          ${omCol("pendingMessageTokens")} = 0,
-          ${omCol("observationTokenCount")} = ?,
-          ${omCol("totalTokensObserved")} = ${omCol("totalTokensObserved")} + ?,
-          ${omCol("observedMessageIds")} = ?,
-          ${omCol("updatedAt")} = ?
-        WHERE ${omCol("id")} = ?`, [
-				input.observations,
-				transformToSqlValue(input.lastObservedAt),
-				input.tokenCount,
-				input.tokenCount,
-				observedMessageIdsJson,
-				transformToSqlValue(now),
-				input.id
-			]);
-			if (result.affectedRows === 0) throwOMNotFound(input.id, "UPDATE_ACTIVE_OBSERVATIONS");
+			return await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, input.id);
+				if (!row) throwOMNotFound(input.id, "UPDATE_ACTIVE_OBSERVATIONS");
+				if (row.supersededBy) return {
+					applied: false,
+					reason: "retired"
+				};
+				if (input.expectedActiveObservations !== void 0 && input.expectedActiveObservations !== (row.activeObservations || "")) return {
+					applied: false,
+					reason: "conflict"
+				};
+				const lastObservedAt = maxObservationCursor(parseDateTime(row.lastObservedAt), input.lastObservedAt);
+				await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
+            ${omCol("activeObservations")} = ?,
+            ${omCol("lastObservedAt")} = ?,
+            ${omCol("pendingMessageTokens")} = 0,
+            ${omCol("observationTokenCount")} = ?,
+            ${omCol("totalTokensObserved")} = ${omCol("totalTokensObserved")} + ?,
+            ${omCol("observedMessageIds")} = ?,
+            ${omCol("updatedAt")} = ?
+          WHERE ${omCol("id")} = ?`, [
+					input.observations,
+					transformToSqlValue(lastObservedAt),
+					input.tokenCount,
+					input.tokenCount,
+					observedMessageIdsJson,
+					transformToSqlValue(/* @__PURE__ */ new Date()),
+					input.id
+				]);
+				return { applied: true };
+			});
 		} catch (error) {
 			rethrowOrWrapOM(error, input.id, "UPDATE_ACTIVE_OBSERVATIONS");
 		}
 	}
 	async createReflectionGeneration(input) {
 		try {
-			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 this.pool.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;
+			const { currentRecord } = input;
+			return await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, currentRecord.id);
+				if (!row) return currentRecord;
+				if (row.supersededBy) return this.parseOMRow(await this.resolveLiveOMRow(connection, row));
+				const stored = this.parseOMRow(row);
+				const plan = planReflectionGenerationText({
+					storedObservations: stored.activeObservations,
+					storedObservationTokenCount: stored.observationTokenCount,
+					snapshotObservations: currentRecord.activeObservations,
+					snapshotObservationTokenCount: currentRecord.observationTokenCount,
+					reflection: input.reflection,
+					tokenCount: input.tokenCount
+				});
+				if (!plan) return stored;
+				return this.rollOverOMRow(connection, stored.id, plan.observations, plan.tokenCount, input.newRecordId, false);
+			});
 		} catch (error) {
 			rethrowOrWrapOM(error, input.currentRecord.id, "CREATE_REFLECTION_GENERATION", { currentRecordId: input.currentRecord.id });
 		}
@@ -7559,20 +7607,22 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 	}
 	async setBufferingObservationFlag(id, isBuffering, lastBufferedAtTokens) {
 		try {
-			const nowSql = transformToSqlValue(/* @__PURE__ */ new Date());
-			const sets = [
-				`${omCol("isBufferingObservation")} = ?`,
-				...lastBufferedAtTokens !== void 0 ? [`${omCol("lastBufferedAtTokens")} = ?`] : [],
-				`${omCol("updatedAt")} = ?`
-			].join(", ");
-			const params = [
-				isBuffering,
-				...lastBufferedAtTokens !== void 0 ? [lastBufferedAtTokens] : [],
-				nowSql,
-				id
-			];
-			const [result] = await this.pool.execute(`UPDATE ${OM_TABLE_QUOTED} SET ${sets} WHERE ${omCol("id")} = ?`, params);
-			if (result.affectedRows === 0) throwOMNotFound(id, "SET_BUFFERING_OBSERVATION_FLAG");
+			await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, id);
+				if (!row) throwOMNotFound(id, "SET_BUFFERING_OBSERVATION_FLAG");
+				const target = await this.resolveLiveOMRow(connection, row);
+				const sets = [
+					`${omCol("isBufferingObservation")} = ?`,
+					...lastBufferedAtTokens !== void 0 ? [`${omCol("lastBufferedAtTokens")} = ?`] : [],
+					`${omCol("updatedAt")} = ?`
+				].join(", ");
+				await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET ${sets} WHERE ${omCol("id")} = ?`, [
+					isBuffering,
+					...lastBufferedAtTokens !== void 0 ? [lastBufferedAtTokens] : [],
+					transformToSqlValue(/* @__PURE__ */ new Date()),
+					target.id
+				]);
+			});
 		} catch (error) {
 			rethrowOrWrapOM(error, id, "SET_BUFFERING_OBSERVATION_FLAG");
 		}
@@ -7593,83 +7643,78 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 	}
 	async setPendingMessageTokens(id, tokenCount) {
 		try {
-			const [result] = await this.pool.execute(`UPDATE ${OM_TABLE_QUOTED} SET
-          ${omCol("pendingMessageTokens")} = ?,
-          ${omCol("updatedAt")} = ?
-        WHERE ${omCol("id")} = ?`, [
-				tokenCount,
-				transformToSqlValue(/* @__PURE__ */ new Date()),
-				id
-			]);
-			if (result.affectedRows === 0) throwOMNotFound(id, "SET_PENDING_MESSAGE_TOKENS");
+			await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, id);
+				if (!row) throwOMNotFound(id, "SET_PENDING_MESSAGE_TOKENS");
+				const target = await this.resolveLiveOMRow(connection, row);
+				await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
+            ${omCol("pendingMessageTokens")} = ?,
+            ${omCol("updatedAt")} = ?
+          WHERE ${omCol("id")} = ?`, [
+					tokenCount,
+					transformToSqlValue(/* @__PURE__ */ new Date()),
+					target.id
+				]);
+			});
 		} catch (error) {
 			rethrowOrWrapOM(error, id, "SET_PENDING_MESSAGE_TOKENS");
 		}
 	}
 	async updateBufferedObservations(input) {
-		try {
-			const connection = await this.pool.getConnection();
-			try {
-				await connection.beginTransaction();
-				const nowSql = transformToSqlValue(/* @__PURE__ */ new Date());
-				const [currentRows] = await connection.execute(`SELECT ${omCol("bufferedObservationChunks")} FROM ${OM_TABLE_QUOTED} WHERE ${omCol("id")} = ? FOR UPDATE`, [input.id]);
-				if (!currentRows || currentRows.length === 0) throwOMNotFound(input.id, "UPDATE_BUFFERED_OBSERVATIONS");
-				const existingChunks = parseBufferedChunks(currentRows[0].bufferedObservationChunks);
-				if (existingChunks.some((existing) => existing.cycleId === input.chunk.cycleId)) {
-					await connection.commit();
-					return;
-				}
-				const newChunk = {
-					id: `ombuf-${globalThis.crypto.randomUUID()}`,
-					cycleId: input.chunk.cycleId,
-					observations: input.chunk.observations,
-					tokenCount: input.chunk.tokenCount,
-					messageIds: input.chunk.messageIds,
-					messageTokens: input.chunk.messageTokens,
-					lastObservedAt: input.chunk.lastObservedAt,
-					createdAt: /* @__PURE__ */ new Date(),
-					suggestedContinuation: input.chunk.suggestedContinuation,
-					currentTask: input.chunk.currentTask,
-					threadTitle: input.chunk.threadTitle,
-					extractedValues: input.chunk.extractedValues,
-					extractionFailures: input.chunk.extractionFailures
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
+		try {
+			const newChunk = {
+				id: `ombuf-${globalThis.crypto.randomUUID()}`,
+				cycleId: input.chunk.cycleId,
+				observations: input.chunk.observations,
+				tokenCount: input.chunk.tokenCount,
+				messageIds: input.chunk.messageIds,
+				messageTokens: input.chunk.messageTokens,
+				lastObservedAt: input.chunk.lastObservedAt,
+				createdAt: /* @__PURE__ */ new Date(),
+				suggestedContinuation: input.chunk.suggestedContinuation,
+				currentTask: input.chunk.currentTask,
+				threadTitle: input.chunk.threadTitle,
+				extractedValues: input.chunk.extractedValues,
+				extractionFailures: input.chunk.extractionFailures
+			};
+			return await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, input.id);
+				if (!row) throwOMNotFound(input.id, "UPDATE_BUFFERED_OBSERVATIONS");
+				const target = await this.resolveLiveOMRow(connection, row);
+				const existingChunks = parseBufferedChunks(target.bufferedObservationChunks);
+				if (existingChunks.some((existing) => existing.cycleId === input.chunk.cycleId) || isBufferedChunkCoveredByCursor(input.chunk.lastObservedAt, parseDateTime(target.lastObservedAt))) return {
+					persisted: false,
+					recordId: target.id
 				};
-				const newChunks = [...existingChunks, newChunk];
-				const lastBufferedAtTime = input.lastBufferedAtTime ? transformToSqlValue(input.lastBufferedAtTime) : null;
-				const [result] = await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
+				const lastBufferedAtTime = maxObservationCursor(parseDateTime(target.lastBufferedAtTime), input.lastBufferedAtTime ?? void 0);
+				await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
             ${omCol("bufferedObservationChunks")} = ?,
-            ${omCol("lastBufferedAtTime")} = COALESCE(?, ${omCol("lastBufferedAtTime")}),
+            ${omCol("lastBufferedAtTime")} = ?,
             ${omCol("updatedAt")} = ?
           WHERE ${omCol("id")} = ?`, [
-					JSON.stringify(newChunks),
-					lastBufferedAtTime,
-					nowSql,
-					input.id
+					JSON.stringify([...existingChunks, newChunk]),
+					transformToSqlValue(lastBufferedAtTime),
+					transformToSqlValue(/* @__PURE__ */ new Date()),
+					target.id
 				]);
-				if (result.affectedRows === 0) throwOMNotFound(input.id, "UPDATE_BUFFERED_OBSERVATIONS");
-				await connection.commit();
-			} catch (error) {
-				await connection.rollback();
-				throw error;
-			} finally {
-				connection.release();
-			}
+				return {
+					persisted: true,
+					recordId: target.id
+				};
+			});
 		} catch (error) {
 			rethrowOrWrapOM(error, input.id, "UPDATE_BUFFERED_OBSERVATIONS");
 		}
 	}
 	async swapBufferedToActive(input) {
-		const connection = await this.pool.getConnection();
 		try {
-			await connection.beginTransaction();
-			const nowSql = transformToSqlValue(/* @__PURE__ */ new Date());
-			const [currentRows] = await connection.execute(`SELECT * FROM ${OM_TABLE_QUOTED} WHERE ${omCol("id")} = ? FOR UPDATE`, [input.id]);
-			if (!currentRows || currentRows.length === 0) throwOMNotFound(input.id, "SWAP_BUFFERED_TO_ACTIVE");
-			const row = currentRows[0];
-			const chunks = parseBufferedChunks(row.bufferedObservationChunks);
-			if (chunks.length === 0) {
-				await connection.commit();
-				return {
+			return await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, input.id);
+				if (!row) throwOMNotFound(input.id, "SWAP_BUFFERED_TO_ACTIVE");
+				const emptyResult = {
 					chunksActivated: 0,
 					messageTokensActivated: 0,
 					observationTokensActivated: 0,
@@ -7677,95 +7722,103 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 					activatedCycleIds: [],
 					activatedMessageIds: []
 				};
-			}
-			const retentionFloor = input.messageTokensThreshold * (1 - input.activationRatio);
-			const targetMessageTokens = Math.max(0, input.currentPendingTokens - retentionFloor);
-			let cumulativeMessageTokens = 0;
-			let bestOverBoundary = 0;
-			let bestOverTokens = 0;
-			let bestUnderBoundary = 0;
-			let bestUnderTokens = 0;
-			for (let i = 0; i < chunks.length; i++) {
-				cumulativeMessageTokens += chunks[i].messageTokens ?? 0;
-				const boundary = i + 1;
-				if (cumulativeMessageTokens >= targetMessageTokens) {
-					if (bestOverBoundary === 0 || cumulativeMessageTokens < bestOverTokens) {
-						bestOverBoundary = boundary;
-						bestOverTokens = cumulativeMessageTokens;
+				if (row.supersededBy) return {
+					...emptyResult,
+					retired: true
+				};
+				const persistedChunks = parseBufferedChunks(row.bufferedObservationChunks);
+				const refreshedWeights = new Map((Array.isArray(input.bufferedChunks) ? input.bufferedChunks : []).map((c) => [c.id, c.messageTokens]));
+				const chunks = persistedChunks.map((c) => refreshedWeights.has(c.id) ? {
+					...c,
+					messageTokens: refreshedWeights.get(c.id)
+				} : c);
+				if (chunks.length === 0) return emptyResult;
+				const retentionFloor = input.messageTokensThreshold * (1 - input.activationRatio);
+				const targetMessageTokens = Math.max(0, input.currentPendingTokens - retentionFloor);
+				let cumulativeMessageTokens = 0;
+				let bestOverBoundary = 0;
+				let bestOverTokens = 0;
+				let bestUnderBoundary = 0;
+				let bestUnderTokens = 0;
+				for (let i = 0; i < chunks.length; i++) {
+					cumulativeMessageTokens += chunks[i].messageTokens ?? 0;
+					const boundary = i + 1;
+					if (cumulativeMessageTokens >= targetMessageTokens) {
+						if (bestOverBoundary === 0 || cumulativeMessageTokens < bestOverTokens) {
+							bestOverBoundary = boundary;
+							bestOverTokens = cumulativeMessageTokens;
+						}
+					} else if (cumulativeMessageTokens > bestUnderTokens) {
+						bestUnderBoundary = boundary;
+						bestUnderTokens = cumulativeMessageTokens;
 					}
-				} else if (cumulativeMessageTokens > bestUnderTokens) {
-					bestUnderBoundary = boundary;
-					bestUnderTokens = cumulativeMessageTokens;
-				}
-			}
-			const maxOvershoot = retentionFloor * .95;
-			const overshoot = bestOverTokens - targetMessageTokens;
-			const remainingAfterOver = input.currentPendingTokens - bestOverTokens;
-			const remainingAfterUnder = input.currentPendingTokens - bestUnderTokens;
-			const minRemaining = Math.min(1e3, retentionFloor);
-			let chunksToActivate;
-			if (input.forceMaxActivation && bestOverBoundary > 0 && remainingAfterOver >= minRemaining) chunksToActivate = bestOverBoundary;
-			else if (bestOverBoundary > 0 && overshoot <= maxOvershoot && remainingAfterOver >= minRemaining) chunksToActivate = bestOverBoundary;
-			else if (bestUnderBoundary > 0 && remainingAfterUnder >= minRemaining) chunksToActivate = bestUnderBoundary;
-			else if (bestOverBoundary > 0) chunksToActivate = bestOverBoundary;
-			else chunksToActivate = 1;
-			const activatedChunks = chunks.slice(0, chunksToActivate);
-			const remainingChunks = chunks.slice(chunksToActivate);
-			const activatedContent = activatedChunks.map((c) => c.observations).join("\n\n");
-			const activatedTokens = activatedChunks.reduce((sum, c) => sum + c.tokenCount, 0);
-			const activatedMessageTokens = activatedChunks.reduce((sum, c) => sum + (c.messageTokens ?? 0), 0);
-			const activatedMessageCount = activatedChunks.reduce((sum, c) => sum + c.messageIds.length, 0);
-			const activatedCycleIds = activatedChunks.map((c) => c.cycleId).filter((cid) => !!cid);
-			const activatedMessageIds = activatedChunks.flatMap((c) => c.messageIds ?? []);
-			const latestChunk = activatedChunks[activatedChunks.length - 1];
-			const lastObservedAtSql = transformToSqlValue(input.lastObservedAt ?? (latestChunk?.lastObservedAt ? new Date(latestChunk.lastObservedAt) : /* @__PURE__ */ new Date()));
-			const existingActive = row.activeObservations || "";
-			const existingTokenCount = Number(row.observationTokenCount || 0);
-			const newActive = existingActive ? `${existingActive}\n\n${activatedContent}` : activatedContent;
-			const newTokenCount = existingTokenCount + activatedTokens;
-			const existingPending = Number(row.pendingMessageTokens || 0);
-			const newPending = Math.max(0, existingPending - activatedMessageTokens);
-			await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
-          ${omCol("activeObservations")} = ?,
-          ${omCol("observationTokenCount")} = ?,
-          ${omCol("pendingMessageTokens")} = ?,
-          ${omCol("bufferedObservationChunks")} = ?,
-          ${omCol("lastObservedAt")} = ?,
-          ${omCol("updatedAt")} = ?
-        WHERE ${omCol("id")} = ?`, [
-				newActive,
-				newTokenCount,
-				newPending,
-				remainingChunks.length > 0 ? JSON.stringify(remainingChunks) : null,
-				lastObservedAtSql,
-				nowSql,
-				input.id
-			]);
-			await connection.commit();
-			const latestChunkHints = activatedChunks[activatedChunks.length - 1];
-			return {
-				chunksActivated: activatedChunks.length,
-				messageTokensActivated: activatedMessageTokens,
-				observationTokensActivated: activatedTokens,
-				messagesActivated: activatedMessageCount,
-				activatedCycleIds,
-				activatedMessageIds,
-				observations: activatedContent,
-				perChunk: activatedChunks.map((c) => ({
-					cycleId: c.cycleId ?? "",
-					messageTokens: c.messageTokens ?? 0,
-					observationTokens: c.tokenCount,
-					messageCount: c.messageIds.length,
-					observations: c.observations
-				})),
-				suggestedContinuation: latestChunkHints?.suggestedContinuation ?? void 0,
-				currentTask: latestChunkHints?.currentTask ?? void 0
-			};
+				}
+				const maxOvershoot = retentionFloor * .95;
+				const overshoot = bestOverTokens - targetMessageTokens;
+				const remainingAfterOver = input.currentPendingTokens - bestOverTokens;
+				const remainingAfterUnder = input.currentPendingTokens - bestUnderTokens;
+				const minRemaining = Math.min(1e3, retentionFloor);
+				let chunksToActivate;
+				if (input.forceMaxActivation && bestOverBoundary > 0 && remainingAfterOver >= minRemaining) chunksToActivate = bestOverBoundary;
+				else if (bestOverBoundary > 0 && overshoot <= maxOvershoot && remainingAfterOver >= minRemaining) chunksToActivate = bestOverBoundary;
+				else if (bestUnderBoundary > 0 && remainingAfterUnder >= minRemaining) chunksToActivate = bestUnderBoundary;
+				else if (bestOverBoundary > 0) chunksToActivate = bestOverBoundary;
+				else chunksToActivate = 1;
+				const activatedChunks = chunks.slice(0, chunksToActivate);
+				const remainingChunks = persistedChunks.slice(chunksToActivate);
+				const activatedContent = activatedChunks.map((c) => c.observations).join("\n\n");
+				const activatedTokens = activatedChunks.reduce((sum, c) => sum + c.tokenCount, 0);
+				const activatedMessageTokens = activatedChunks.reduce((sum, c) => sum + (c.messageTokens ?? 0), 0);
+				const activatedMessageCount = activatedChunks.reduce((sum, c) => sum + c.messageIds.length, 0);
+				const activatedCycleIds = activatedChunks.map((c) => c.cycleId).filter((cid) => !!cid);
+				const activatedMessageIds = activatedChunks.flatMap((c) => c.messageIds ?? []);
+				const latestChunk = activatedChunks[activatedChunks.length - 1];
+				const derivedLastObservedAt = input.lastObservedAt ?? (latestChunk?.lastObservedAt ? new Date(latestChunk.lastObservedAt) : /* @__PURE__ */ new Date());
+				const lastObservedAt = maxObservationCursor(parseDateTime(row.lastObservedAt), derivedLastObservedAt);
+				const existingActive = row.activeObservations || "";
+				const existingTokenCount = Number(row.observationTokenCount || 0);
+				const newActive = existingActive ? `${existingActive}\n\n${activatedContent}` : activatedContent;
+				const newTokenCount = existingTokenCount + activatedTokens;
+				const existingPending = Number(row.pendingMessageTokens || 0);
+				const newPending = Math.max(0, existingPending - activatedMessageTokens);
+				await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
+            ${omCol("activeObservations")} = ?,
+            ${omCol("observationTokenCount")} = ?,
+            ${omCol("pendingMessageTokens")} = ?,
+            ${omCol("bufferedObservationChunks")} = ?,
+            ${omCol("lastObservedAt")} = ?,
+            ${omCol("updatedAt")} = ?
+          WHERE ${omCol("id")} = ?`, [
+					newActive,
+					newTokenCount,
+					newPending,
+					remainingChunks.length > 0 ? JSON.stringify(remainingChunks) : null,
+					transformToSqlValue(lastObservedAt),
+					transformToSqlValue(/* @__PURE__ */ new Date()),
+					input.id
+				]);
+				const latestChunkHints = activatedChunks[activatedChunks.length - 1];
+				return {
+					chunksActivated: activatedChunks.length,
+					messageTokensActivated: activatedMessageTokens,
+					observationTokensActivated: activatedTokens,
+					messagesActivated: activatedMessageCount,
+					activatedCycleIds,
+					activatedMessageIds,
+					observations: activatedContent,
+					perChunk: activatedChunks.map((c) => ({
+						cycleId: c.cycleId ?? "",
+						messageTokens: c.messageTokens ?? 0,
+						observationTokens: c.tokenCount,
+						messageCount: c.messageIds.length,
+						observations: c.observations
+					})),
+					suggestedContinuation: latestChunkHints?.suggestedContinuation ?? void 0,
+					currentTask: latestChunkHints?.currentTask ?? void 0
+				};
+			});
 		} catch (error) {
-			await connection.rollback();
 			rethrowOrWrapOM(error, input.id, "SWAP_BUFFERED_TO_ACTIVE");
-		} finally {
-			connection.release();
 		}
 	}
 	async updateBufferedReflection(input) {
@@ -7798,38 +7851,182 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 	}
 	async swapBufferedReflectionToActive(input) {
 		try {
-			const [currentRows] = await this.pool.execute(`SELECT * FROM ${OM_TABLE_QUOTED} WHERE ${omCol("id")} = ?`, [input.currentRecord.id]);
-			if (!currentRows || currentRows.length === 0) throwOMNotFound(input.currentRecord.id, "SWAP_BUFFERED_REFLECTION_TO_ACTIVE");
-			const row = currentRows[0];
-			const bufferedReflection = row.bufferedReflection || "";
-			const reflectedLineCount = Number(row.reflectedObservationLineCount || 0);
-			if (!bufferedReflection) throw new MastraError({
-				id: createStorageErrorId("MYSQL", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NO_CONTENT"),
-				text: "No buffered reflection to swap",
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.USER,
-				details: { id: input.currentRecord.id }
-			});
-			const unreflectedContent = (row.activeObservations || "").split("\n").slice(reflectedLineCount).join("\n").trim();
-			const newObservations = unreflectedContent ? `${bufferedReflection}\n\n${unreflectedContent}` : bufferedReflection;
-			const newRecord = await this.createReflectionGeneration({
-				currentRecord: input.currentRecord,
-				reflection: newObservations,
-				tokenCount: input.tokenCount
+			const { currentRecord } = input;
+			return await this.withOMTransaction(async (connection) => {
+				const row = await this.lockOMRow(connection, currentRecord.id);
+				if (!row) return currentRecord;
+				if (row.supersededBy) return this.parseOMRow(await this.resolveLiveOMRow(connection, row));
+				const stored = this.parseOMRow(row);
+				const bufferedReflection = stored.bufferedReflection || "";
+				if (!bufferedReflection) throw new MastraError({
+					id: createStorageErrorId("MYSQL", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NO_CONTENT"),
+					text: "No buffered reflection to swap",
+					domain: ErrorDomain.STORAGE,
+					category: ErrorCategory.USER,
+					details: { id: currentRecord.id }
+				});
+				if (!isAppendOnlySince(stored.activeObservations, currentRecord.activeObservations)) return stored;
+				const reflectedLineCount = stored.reflectedObservationLineCount ?? 0;
+				const unreflectedContent = (stored.activeObservations || "").split("\n").slice(reflectedLineCount).join("\n").trim();
+				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);
 			});
-			const nowSql = transformToSqlValue(/* @__PURE__ */ new Date());
-			await this.pool.execute(`UPDATE ${OM_TABLE_QUOTED} SET
-          ${omCol("bufferedReflection")} = NULL,
-          ${omCol("bufferedReflectionTokens")} = NULL,
-          ${omCol("bufferedReflectionInputTokens")} = NULL,
-          ${omCol("reflectedObservationLineCount")} = NULL,
-          ${omCol("updatedAt")} = ?
-        WHERE ${omCol("id")} = ?`, [nowSql, input.currentRecord.id]);
-			return newRecord;
 		} catch (error) {
 			rethrowOrWrapOM(error, input.currentRecord.id, "SWAP_BUFFERED_REFLECTION_TO_ACTIVE");
 		}
 	}
+	/**
+	* Runs `fn` in one transaction on a dedicated connection. Every OM lifecycle write locks its
+	* target row by primary key (`SELECT … FOR UPDATE`, a record lock — never a range), so the
+	* 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) {
+		for (let attempt = 1;; attempt++) {
+			const connection = await this.pool.getConnection();
+			try {
+				await connection.beginTransaction();
+				const result = await fn(connection);
+				await connection.commit();
+				return result;
+			} catch (error) {
+				await connection.rollback().catch(() => {});
+				if (attempt < OM_MAX_TRANSACTION_ATTEMPTS && isRetryableLockError(error)) continue;
+				throw error;
+			} finally {
+				connection.release();
+			}
+		}
+	}
+	/** Row-locks one OM record by primary key for the rest of the transaction. */
+	async lockOMRow(connection, id) {
+		const [rows] = await connection.execute(`SELECT * FROM ${OM_TABLE_QUOTED} WHERE ${omCol("id")} = ? FOR UPDATE`, [id]);
+		return rows?.[0] ?? null;
+	}
+	/**
+	* The live, row-locked record a lifecycle write aimed at `row` lands on: `row` itself while
+	* live, otherwise the head. The head is found with a plain (non-locking, so no range locks)
+	* canonical head read, then locked by primary key. Under REPEATABLE READ that read can predate
+	* a rollover committed after this transaction started; the locking read sees the latest
+	* committed row, so a head retired since is followed through `supersededBy` (bounded).
+	*/
+	async resolveLiveOMRow(connection, row) {
+		if (!row.supersededBy) return row;
+		const [heads] = await connection.execute(`SELECT id FROM ${OM_TABLE_QUOTED} WHERE ${omCol("lookupKey")} = ? ORDER BY ${OM_HEAD_ORDER} LIMIT 1`, [row.lookupKey]);
+		const headId = heads?.[0]?.id ?? row.supersededBy;
+		let current = await this.lockOMRow(connection, headId) ?? row;
+		for (let hop = 0; current.supersededBy; hop++) {
+			const next = hop < OM_MAX_HEAD_HOPS ? await this.lockOMRow(connection, current.supersededBy) : null;
+			if (!next) throw new MastraError({
+				id: createStorageErrorId("MYSQL", "RESOLVE_OBSERVATIONAL_MEMORY_HEAD", "FAILED"),
+				text: `Observational memory record ${row.id} is superseded but no live head was found`,
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { id: row.id }
+			});
+			current = next;
+		}
+		return current;
+	}
+	/**
+	* Create the next generation from the stored (live, row-locked) record and retire the stored
+	* record in the same transaction. Carried columns are copied in SQL from the stored row, so
+	* nothing round-trips through a client-side date conversion. Buffered chunks move to the new
+	* generation; the cursor, buffering markers, flags, and counters carry over; buffered
+	* reflection state does not (and is cleared on the retired row after a buffered swap).
+	*/
+	async rollOverOMRow(connection, storedId, observations, tokenCount, newRecordId, clearBufferedReflection) {
+		const id = newRecordId ?? globalThis.crypto.randomUUID();
+		const nowSql = transformToSqlValue(/* @__PURE__ */ new Date());
+		const c = omCol;
+		await connection.execute(`INSERT INTO ${OM_TABLE_QUOTED} (
+        ${c("id")}, ${c("lookupKey")}, ${c("scope")}, ${c("resourceId")}, ${c("threadId")},
+        ${c("activeObservations")}, ${c("activeObservationsPendingUpdate")},
+        ${c("originType")}, ${c("config")}, ${c("generationCount")}, ${c("lastObservedAt")}, ${c("lastReflectionAt")},
+        ${c("pendingMessageTokens")}, ${c("totalTokensObserved")}, ${c("observationTokenCount")}, ${c("bufferedObservationChunks")},
+        ${c("isObserving")}, ${c("isReflecting")}, ${c("isBufferingObservation")}, ${c("isBufferingReflection")},
+        ${c("lastBufferedAtTokens")}, ${c("lastBufferedAtTime")},
+        ${c("observedTimezone")}, ${c("metadata")}, ${c("supersededBy")}, ${c("createdAt")}, ${c("updatedAt")}
+      )
+      SELECT
+        ?, ${c("lookupKey")}, ${c("scope")}, ${c("resourceId")}, ${c("threadId")},
+        ?, NULL,
+        'reflection', ${c("config")}, ${c("generationCount")} + 1, ${c("lastObservedAt")}, ?,
+        ${c("pendingMessageTokens")}, ${c("totalTokensObserved")}, ?, ${c("bufferedObservationChunks")},
+        false, false, ${c("isBufferingObservation")}, false,
+        ${c("lastBufferedAtTokens")}, ${c("lastBufferedAtTime")},
+        ${c("observedTimezone")}, ${c("metadata")}, NULL, ?, ?
+      FROM ${OM_TABLE_QUOTED} WHERE ${c("id")} = ?`, [
+			id,
+			observations,
+			nowSql,
+			Math.round(tokenCount),
+			nowSql,
+			nowSql,
+			storedId
+		]);
+		const [retired] = await connection.execute(`UPDATE ${OM_TABLE_QUOTED} SET
+        ${c("supersededBy")} = ?,
+        ${c("bufferedObservationChunks")} = NULL,
+        ${clearBufferedReflection ? `${c("bufferedReflection")} = NULL, ${c("bufferedReflectionTokens")} = NULL,
+        ${c("bufferedReflectionInputTokens")} = NULL, ${c("reflectedObservationLineCount")} = NULL,` : ""}
+        ${c("updatedAt")} = ?
+      WHERE ${c("id")} = ? AND ${c("supersededBy")} IS NULL`, [
+			id,
+			nowSql,
+			storedId
+		]);
+		if (retired.affectedRows !== 1) throw new MastraError({
+			id: createStorageErrorId("MYSQL", "CREATE_REFLECTION_GENERATION", "RETIRE_FAILED"),
+			text: `Failed to retire observational memory record ${storedId}`,
+			domain: ErrorDomain.STORAGE,
+			category: ErrorCategory.THIRD_PARTY,
+			details: { id: storedId }
+		});
+		const inserted = await this.lockOMRow(connection, id);
+		if (!inserted) throwOMNotFound(id, "CREATE_REFLECTION_GENERATION");
+		return this.parseOMRow(inserted);
+	}
+	/**
+	* Retire every live row that sorts after its key's canonical head, marking it superseded by
+	* the head. Rows retired by older adapter versions (which never set `supersededBy`) become
+	* frozen. Only keys with more than one live row are touched; each update embeds the head's
+	* ordering key, so a row created by a concurrent rollover (a newer generation) never matches.
+	* Runs at READ COMMITTED so the scan takes no gap locks.
+	*/
+	async backfillSupersededBy() {
+		const [keys] = await this.pool.execute(`SELECT ${omCol("lookupKey")} AS lookupKey FROM ${OM_TABLE_QUOTED}
+      WHERE ${omCol("supersededBy")} IS NULL GROUP BY ${omCol("lookupKey")} HAVING COUNT(*) > 1`);
+		for (const { lookupKey } of keys ?? []) for (let attempt = 1;; attempt++) {
+			const connection = await this.pool.getConnection();
+			try {
+				await connection.query("SET TRANSACTION ISOLATION LEVEL READ COMMITTED");
+				await connection.beginTransaction();
+				await connection.execute(`UPDATE ${OM_TABLE_QUOTED} AS r
+            JOIN (
+              SELECT ${omCol("id")} AS id, ${omCol("generationCount")} AS generationCount, ${omCol("createdAt")} AS createdAt
+              FROM ${OM_TABLE_QUOTED} WHERE ${omCol("lookupKey")} = ? ORDER BY ${OM_HEAD_ORDER} LIMIT 1
+            ) AS h
+            SET r.${omCol("supersededBy")} = h.id
+            WHERE r.${omCol("lookupKey")} = ?
+              AND r.${omCol("supersededBy")} IS NULL
+              AND (
+                r.${omCol("generationCount")} < h.generationCount
+                OR (r.${omCol("generationCount")} = h.generationCount AND r.${omCol("createdAt")} > h.createdAt)
+                OR (r.${omCol("generationCount")} = h.generationCount AND r.${omCol("createdAt")} = h.createdAt AND r.${omCol("id")} > h.id)
+              )`, [lookupKey, lookupKey]);
+				await connection.commit();
+				break;
+			} catch (error) {
+				await connection.rollback().catch(() => {});
+				if (attempt < OM_MAX_TRANSACTION_ATTEMPTS && isRetryableLockError(error)) continue;
+				throw error;
+			} finally {
+				connection.release();
+			}
+		}
+	}
 	async updateOMFlag(id, column, value, operation) {
 		try {
 			const [result] = await this.pool.execute(`UPDATE ${OM_TABLE_QUOTED} SET ${omCol(column)} = ?, ${omCol("updatedAt")} = ? WHERE ${omCol("id")} = ?`, [
@@ -7877,7 +8074,8 @@ var MemoryMySQL = class MemoryMySQL extends MemoryStorage {
 			config: parseJSONColumn(row.config) ?? {},
 			metadata: parseJSONColumn(row.metadata),
 			observedMessageIds: parseJSONColumn(row.observedMessageIds),
-			observedTimezone: row.observedTimezone || void 0
+			observedTimezone: row.observedTimezone || void 0,
+			supersededBy: row.supersededBy ?? null
 		};
 	}
 };