@mastra/mongodb 1.23.0 → 1.23.1-alpha.1

package/dist/index.js

@@ -1,14 +1,15 @@
 import { v4 } from "@lukeed/uuid";
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
-import { AgentsStorage, BackgroundTasksStorage, BlobStore, DatasetsStorage, ExperimentsStorage, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MastraCompositeStore, MemoryStorage, NotificationsStorage, ObservabilityStorage, PromptBlocksStorage, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, 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_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TraceStatus, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, hasErrorCode, isKnowledgeScopeVisible, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { AgentsStorage, BackgroundTasksStorage, BlobStore, DatasetsStorage, ExperimentsStorage, KnowledgeConflictError, KnowledgeNotFoundError, KnowledgeStorage, MCPClientsStorage, MCPServersStorage, MastraCompositeStore, MemoryStorage, NotificationsStorage, ObservabilityStorage, PromptBlocksStorage, RunFenceConflictError, SchedulesStorage, ScorerDefinitionsStorage, ScoresStorage, SkillsStorage, TABLE_AGENTS, TABLE_AGENT_VERSIONS, TABLE_BACKGROUND_TASKS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, 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_MEMORY_RUN_FENCES, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_RUN_OWNERS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TraceStatus, WorkflowDefinitionsStorage, WorkflowsStorage, WorkspacesStorage, calculatePagination, canonicalizeKnowledgeScope, createKnowledgeUlid, createStorageErrorId, createVectorErrorId, ensureDate, hasErrorCode, isKnowledgeScopeVisible, isRunFenceConflictError, knowledgeScopeKey, knowledgeSemanticDocumentId, knowledgeSemanticIdempotencyKey, listTracesArgsSchema, normalizePerPage, normalizeScheduleTarget, parseDuration, parseKnowledgeNodeCursor, parseKnowledgeWikilinks, resolveListOrderBy, resolveRunFence, safelyParseJSON, storageMessageMatchesMetadataFilter, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { MastraVector, validateUpsertInput, validateVectorValues } from "@mastra/core/vector";
 import { MongoBulkWriteError, MongoClient, ObjectId } from "mongodb";
 import { BaseFilterTranslator } from "@mastra/core/vector/filter";
+import { createHash } from "crypto";
 import { MessageList } from "@mastra/core/agent";
 import { saveScorePayloadSchema } from "@mastra/core/evals";
 import { skillSnapshotFieldValuesEqual } from "@mastra/core/storage/domains/skills";
 //#region package.json
-var version = "1.23.0";
+var version = "1.23.1-alpha.1";
 //#endregion
 //#region src/vector/filter.ts
 /**
@@ -1617,20 +1618,29 @@ var MongoDBConnector = class MongoDBConnector {
 		return (await this.getConnection()).listCollections({ name: collectionName }).hasNext();
 	}
 	/**
-	* Returns true when the deployment supports multi-document transactions
-	* (replica set or sharded cluster). Standalone servers and custom connector
-	* handlers return false. Probed once and cached.
+	* Whether the deployment supports multi-document transactions (replica set
+	* or sharded cluster). Standalone servers and custom connector handlers
+	* don't. The answer is cached once a probe completes; a probe that fails
+	* rejects and is retried on the next call, so the answer never changes.
 	*/
-	async supportsTransactions() {
+	async probeTransactions() {
 		if (this.#supportsTransactions !== void 0) return this.#supportsTransactions;
 		if (!this.#client) {
 			this.#supportsTransactions = false;
 			return false;
 		}
+		const hello = await (await this.getConnection()).admin().command({ hello: 1 });
+		this.#supportsTransactions = Boolean(hello.setName) || hello.msg === "isdbgrid";
+		return this.#supportsTransactions;
+	}
+	/**
+	* Like {@link probeTransactions}, but a failed probe reads as no
+	* transaction support (and is retried on the next call), so a momentary
+	* outage degrades writes to non-atomic instead of failing them.
+	*/
+	async supportsTransactions() {
 		try {
-			const hello = await (await this.getConnection()).admin().command({ hello: 1 });
-			this.#supportsTransactions = Boolean(hello.setName) || hello.msg === "isdbgrid";
-			return this.#supportsTransactions;
+			return await this.probeTransactions();
 		} catch {
 			return false;
 		}
@@ -2277,14 +2287,19 @@ function cutoffFor(policy, encoding, now = Date.now()) {
 * Delete up to `limit` documents whose anchor field is older than `cutoff`.
 *
 * `deleteMany` has no limit clause, so each batch first collects `_id`s with a
-* bounded `find`, then deletes exactly that set — the Mongo equivalent of the
-* SQL stores' `DELETE ... WHERE rowid/ctid IN (SELECT ... LIMIT n)` pattern.
+* bounded `find`, then deletes that set — the Mongo equivalent of the SQL
+* stores' `DELETE ... WHERE rowid/ctid IN (SELECT ... LIMIT n)` pattern. The
+* delete re-checks the anchor, so a document updated after the `find` (a
+* renewed run ownership, a touched snapshot) survives.
 */
 async function pruneCollectionBatch({ connector, table, column, cutoff, limit }) {
 	const collection = await connector.getCollection(table);
 	const docs = await collection.find({ [column]: { $lt: cutoff } }).project({ _id: 1 }).limit(limit).toArray();
 	if (docs.length === 0) return 0;
-	return (await collection.deleteMany({ _id: { $in: docs.map((doc) => doc._id) } })).deletedCount;
+	return (await collection.deleteMany({
+		_id: { $in: docs.map((doc) => doc._id) },
+		[column]: { $lt: cutoff }
+	})).deletedCount;
 }
 /**
 * Run the bounded/cancellable batched-delete loop for a single logical target,
@@ -6494,6 +6509,105 @@ var MongoDBMCPServersStorage = class MongoDBMCPServersStorage extends MCPServers
 	}
 };
 //#endregion
+//#region ../../packages/_internal-core/dist/memory/index.js
+/**
+* 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/run-fencing.ts
+async function getRunClaims(connector, name) {
+	return await connector.getCollection(name);
+}
+/** Duplicate-key error: an upsert lost the race to insert the document. */
+function isDuplicateKeyError(error) {
+	return error?.code === 11e3;
+}
+/**
+* Runs a write, fenced when `check` is set. A fenced write runs in a
+* transaction that first updates the run's claim document, matching it on
+* the fence. A fence that is no longer current matches nothing, and the write
+* throws `RunFenceConflictError` before anything is written. A claim that
+* changes while the transaction runs makes the update conflict, so the
+* transaction retries and sees the new claim; a claim attempted after the
+* update waits until the transaction commits. Updating the claim document,
+* rather than reading it, is what makes concurrent claims conflict.
+*
+* Fencing is declared only on deployments that support transactions.
+*/
+async function withRunFence(connector, check, write) {
+	if (!check) return write();
+	const { claims, fence, operation } = check;
+	const collection = await getRunClaims(connector, claims);
+	return connector.withTransaction(async (session) => {
+		if ((await collection.updateOne({
+			_id: fence.runId,
+			generation: fence.generation,
+			ownerId: fence.ownerId
+		}, { $inc: { fencedWrites: 1 } }, { session })).matchedCount === 0) throw new RunFenceConflictError(fence, operation);
+		return write(session);
+	});
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 /**
 * Local constant for the observational memory table name.
@@ -6501,6 +6615,95 @@ var MongoDBMCPServersStorage = class MongoDBMCPServersStorage extends MCPServers
 * versions that don't export TABLE_OBSERVATIONAL_MEMORY.
 */
 const OM_TABLE = "mastra_observational_memory";
+/** Canonical head order: newest generation, then earliest createdAt, then lowest id. */
+const OM_HEAD_SORT = {
+	generationCount: -1,
+	createdAt: 1,
+	id: 1
+};
+/** Max redirects when a write aimed at a retired record follows the head. */
+const OM_MAX_HEAD_HOPS = 3;
+/** Max read-decide-conditional-update rounds before giving up on a contended record. */
+const OM_MAX_CONDITIONAL_ATTEMPTS = 3;
+/** Document `_id` of a key's generation-0 record; see `initializeObservationalMemory`. */
+function getGeneration0DocumentId(lookupKey) {
+	return `om0_${createHash("sha256").update(lookupKey).digest("hex").slice(0, 32)}`;
+}
+/**
+* The successor document of a fenced (frozen) document: a pure function of the old document's
+* final state and the rollover inputs, so concurrent roll-forwards insert identical documents.
+* Buffered chunks, the cursor, buffering markers, flags, and counters carry over; buffered
+* reflection state does not.
+*/
+function buildSuccessorDocument(old, pending) {
+	let activeObservations = pending.reflection;
+	let observationTokenCount = pending.tokenCount;
+	if (pending.mode === "append") {
+		const tail = String(old.activeObservations ?? "").slice(pending.snapTextLength).trimStart();
+		activeObservations = pending.reflection ? `${pending.reflection}\n\n${tail}` : tail;
+		observationTokenCount = pending.tokenCount + Math.max(0, Number(old.observationTokenCount || 0) - pending.snapObservationTokenCount);
+	}
+	return {
+		id: pending.newId,
+		lookupKey: old.lookupKey,
+		scope: old.scope,
+		resourceId: old.resourceId,
+		threadId: old.threadId ?? null,
+		activeObservations,
+		activeObservationsPendingUpdate: null,
+		originType: "reflection",
+		config: old.config ?? null,
+		generationCount: Number(old.generationCount || 0) + 1,
+		lastObservedAt: old.lastObservedAt ?? null,
+		lastReflectionAt: pending.createdAt,
+		pendingMessageTokens: old.pendingMessageTokens ?? 0,
+		totalTokensObserved: old.totalTokensObserved ?? 0,
+		observationTokenCount,
+		bufferedObservationChunks: Array.isArray(old.bufferedObservationChunks) ? old.bufferedObservationChunks : [],
+		isObserving: false,
+		isReflecting: false,
+		isBufferingObservation: Boolean(old.isBufferingObservation),
+		isBufferingReflection: false,
+		lastBufferedAtTokens: old.lastBufferedAtTokens ?? 0,
+		lastBufferedAtTime: old.lastBufferedAtTime ?? null,
+		observedTimezone: old.observedTimezone ?? null,
+		metadata: old.metadata ?? null,
+		supersededBy: null,
+		createdAt: pending.createdAt,
+		updatedAt: pending.createdAt
+	};
+}
+/** Equality filters for `fields` as stored in `doc` (`$exists: false` for absent fields). */
+function matchStoredFields(doc, fields) {
+	return Object.fromEntries(fields.map((f) => [f, doc[f] === void 0 ? { $exists: false } : doc[f]]));
+}
+function omNotFound(operation, id) {
+	return new MastraError({
+		id: createStorageErrorId("MONGODB", operation, "NOT_FOUND"),
+		text: `Observational memory record not found: ${id}`,
+		domain: ErrorDomain.STORAGE,
+		category: ErrorCategory.THIRD_PARTY,
+		details: { id }
+	});
+}
+function omConflict(operation, id) {
+	return new MastraError({
+		id: createStorageErrorId("MONGODB", operation, "CONFLICT"),
+		text: `Observational memory record ${id} kept changing during ${operation}; giving up after ${OM_MAX_CONDITIONAL_ATTEMPTS} attempts`,
+		domain: ErrorDomain.STORAGE,
+		category: ErrorCategory.THIRD_PARTY,
+		details: { id }
+	});
+}
+function omNoLiveHead(id) {
+	return new MastraError({
+		id: createStorageErrorId("MONGODB", "RESOLVE_OBSERVATIONAL_MEMORY_HEAD", "FAILED"),
+		text: `Observational memory record ${id} is superseded but no live head was found`,
+		domain: ErrorDomain.STORAGE,
+		category: ErrorCategory.THIRD_PARTY,
+		details: { id }
+	});
+}
 var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	supportsPartialThreadUpdate = true;
 	supportsObservationalMemory = true;
@@ -6513,11 +6716,14 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 		TABLE_THREADS,
 		TABLE_MESSAGES,
 		TABLE_RESOURCES,
-		OM_TABLE
+		OM_TABLE,
+		TABLE_MEMORY_RUN_FENCES
 	];
 	/**
 	* Retention-eligible collections. The observational-memory collection is
 	* excluded: it has no timestamp anchor to age on. All anchors are BSON dates.
+	* A run fence's `retiredAt` stays null until the execution holding it
+	* settles, and null is never pruned.
 	*/
 	static retentionTables = {
 		messages: {
@@ -6534,6 +6740,11 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			table: TABLE_THREADS,
 			column: "createdAt",
 			indexed: true
+		},
+		runFences: {
+			table: TABLE_MEMORY_RUN_FENCES,
+			column: "retiredAt",
+			indexed: true
 		}
 	};
 	constructor(config) {
@@ -6548,13 +6759,80 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	async init() {
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
+		await this.#warnIfOMIdIndexMissing();
+		await this.#maintainSupersededBy();
+	}
+	/**
+	* Fenced writes need multi-document transactions, so only replica sets and
+	* sharded clusters fence. Rejects while the deployment can't be probed.
+	*/
+	supportsRunFencing() {
+		return this.#connector.probeTransactions();
+	}
+	async raiseRunFence(fence) {
+		try {
+			const fences = await getRunClaims(this.#connector, TABLE_MEMORY_RUN_FENCES);
+			for (;;) {
+				try {
+					await fences.updateOne({
+						_id: fence.runId,
+						$or: [{ generation: { $lt: fence.generation } }, {
+							generation: fence.generation,
+							ownerId: fence.ownerId
+						}]
+					}, { $set: {
+						generation: fence.generation,
+						ownerId: fence.ownerId,
+						retiredAt: null
+					} }, { upsert: true });
+					return true;
+				} catch (error) {
+					if (!isDuplicateKeyError(error)) throw error;
+				}
+				const current = await fences.findOne({ _id: fence.runId });
+				if (current && current.generation >= fence.generation) return current.generation === fence.generation && current.ownerId === fence.ownerId;
+			}
+		} catch (error) {
+			throw new MastraError({
+				id: createStorageErrorId("MONGODB", "RAISE_RUN_FENCE", "FAILED"),
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	async retireRunFence(fence) {
+		try {
+			return (await (await getRunClaims(this.#connector, TABLE_MEMORY_RUN_FENCES)).updateOne({
+				_id: fence.runId,
+				generation: fence.generation,
+				ownerId: fence.ownerId
+			}, [{ $set: { retiredAt: "$$NOW" } }])).matchedCount > 0;
+		} catch (error) {
+			throw new MastraError({
+				id: createStorageErrorId("MONGODB", "RETIRE_RUN_FENCE", "FAILED"),
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { runId: fence.runId }
+			}, error);
+		}
+	}
+	/** The check a write must pass: its own fence, otherwise the one in scope. */
+	#runFenceCheck(fence, operation) {
+		const resolved = resolveRunFence(this, fence);
+		return resolved && {
+			claims: TABLE_MEMORY_RUN_FENCES,
+			fence: resolved,
+			operation
+		};
 	}
 	/**
 	* Delete memory rows older than each table's `maxAge`, batched. Order is
 	* messages → resources → threads so child rows never outlive the delete of
-	* their thread. Like `deleteThread()`, this does not sweep vector-store
-	* embeddings — semantic-recall vectors live in a separate vector store the
-	* memory domain cannot reach; cleaning those up is the operator's concern.
+	* their thread; run fences are independent and go last. Like
+	* `deleteThread()`, this does not sweep vector-store embeddings —
+	* semantic-recall vectors live in a separate vector store the memory domain
+	* cannot reach; cleaning those up is the operator's concern.
 	*/
 	async prune(policies, options) {
 		const targets = resolveTargets({
@@ -6563,7 +6841,8 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			order: [
 				"messages",
 				"resources",
-				"threads"
+				"threads",
+				"runFences"
 			]
 		});
 		return runPrune({
@@ -6669,17 +6948,19 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 		}
 	}
 	async dangerouslyClearAll() {
-		const [threadsCollection, messagesCollection, resourcesCollection, omCollection] = await Promise.all([
+		const [threadsCollection, messagesCollection, resourcesCollection, omCollection, fencesCollection] = await Promise.all([
 			this.getCollection(TABLE_THREADS),
 			this.getCollection(TABLE_MESSAGES),
 			this.getCollection(TABLE_RESOURCES),
-			this.getCollection(OM_TABLE)
+			this.getCollection(OM_TABLE),
+			this.getCollection(TABLE_MEMORY_RUN_FENCES)
 		]);
 		await Promise.all([
 			threadsCollection.deleteMany({}),
 			messagesCollection.deleteMany({}),
 			resourcesCollection.deleteMany({}),
-			omCollection.deleteMany({})
+			omCollection.deleteMany({}),
+			fencesCollection.deleteMany({})
 		]);
 	}
 	parseRow(row) {
@@ -7035,7 +7316,7 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async saveMessages({ messages }) {
+	async saveMessages({ messages, fence }) {
 		if (messages.length === 0) return { messages: [] };
 		try {
 			if (!messages[0]?.threadId) throw new Error("Thread ID is required");
@@ -7063,12 +7344,16 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			});
 			const allThreadIds = new Set(messages.map((m) => m.threadId));
 			const now = /* @__PURE__ */ new Date();
-			await this.#connector.withTransaction(async (session) => {
+			const writeMessages = async (session) => {
 				await collection.bulkWrite(messagesToInsert, { session });
 				for (const tid of allThreadIds) await threadsCollection.updateOne({ id: tid }, { $set: { updatedAt: now } }, { session });
-			});
+			};
+			const check = this.#runFenceCheck(fence, "saveMessages");
+			if (check) await withRunFence(this.#connector, check, writeMessages);
+			else await this.#connector.withTransaction(writeMessages);
 			return { messages: new MessageList().add(messages, "memory").get.all.db() };
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "SAVE_MESSAGES", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7076,49 +7361,51 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateMessages({ messages }) {
+	async updateMessages({ messages, fence }) {
 		if (messages.length === 0) return [];
 		const messageIds = messages.map((m) => m.id);
 		const collection = await this.getCollection(TABLE_MESSAGES);
-		const existingMessagesParsed = (await collection.find({ id: { $in: messageIds } }).toArray()).map((msg) => this.parseRow(msg));
-		if (existingMessagesParsed.length === 0) return [];
-		const threadIdsToUpdate = /* @__PURE__ */ new Set();
-		const bulkOps = [];
-		for (const existingMessage of existingMessagesParsed) {
-			const updatePayload = messages.find((m) => m.id === existingMessage.id);
-			if (!updatePayload) continue;
-			const { id, ...fieldsToUpdate } = updatePayload;
-			if (Object.keys(fieldsToUpdate).length === 0) continue;
-			threadIdsToUpdate.add(existingMessage.threadId);
-			if (updatePayload.threadId && updatePayload.threadId !== existingMessage.threadId) threadIdsToUpdate.add(updatePayload.threadId);
-			const updateDoc = {};
-			const updatableFields = { ...fieldsToUpdate };
-			if (updatableFields.content) {
-				const newContent = {
-					...existingMessage.content,
-					...updatableFields.content,
-					...existingMessage.content?.metadata && updatableFields.content.metadata ? { metadata: {
-						...existingMessage.content.metadata,
-						...updatableFields.content.metadata
-					} } : {}
-				};
-				updateDoc.content = JSON.stringify(newContent);
-				delete updatableFields.content;
-			}
-			for (const key in updatableFields) if (Object.prototype.hasOwnProperty.call(updatableFields, key)) {
-				const dbKey = key === "threadId" ? "thread_id" : key;
-				let value = updatableFields[key];
-				if (typeof value === "object" && value !== null) value = JSON.stringify(value);
-				updateDoc[dbKey] = value;
+		return withRunFence(this.#connector, this.#runFenceCheck(fence, "updateMessages"), async (session) => {
+			const existingMessagesParsed = (await collection.find({ id: { $in: messageIds } }, { session }).toArray()).map((msg) => this.parseRow(msg));
+			if (existingMessagesParsed.length === 0) return [];
+			const threadIdsToUpdate = /* @__PURE__ */ new Set();
+			const bulkOps = [];
+			for (const existingMessage of existingMessagesParsed) {
+				const updatePayload = messages.find((m) => m.id === existingMessage.id);
+				if (!updatePayload) continue;
+				const { id, ...fieldsToUpdate } = updatePayload;
+				if (Object.keys(fieldsToUpdate).length === 0) continue;
+				threadIdsToUpdate.add(existingMessage.threadId);
+				if (updatePayload.threadId && updatePayload.threadId !== existingMessage.threadId) threadIdsToUpdate.add(updatePayload.threadId);
+				const updateDoc = {};
+				const updatableFields = { ...fieldsToUpdate };
+				if (updatableFields.content) {
+					const newContent = {
+						...existingMessage.content,
+						...updatableFields.content,
+						...existingMessage.content?.metadata && updatableFields.content.metadata ? { metadata: {
+							...existingMessage.content.metadata,
+							...updatableFields.content.metadata
+						} } : {}
+					};
+					updateDoc.content = JSON.stringify(newContent);
+					delete updatableFields.content;
+				}
+				for (const key in updatableFields) if (Object.prototype.hasOwnProperty.call(updatableFields, key)) {
+					const dbKey = key === "threadId" ? "thread_id" : key;
+					let value = updatableFields[key];
+					if (typeof value === "object" && value !== null) value = JSON.stringify(value);
+					updateDoc[dbKey] = value;
+				}
+				if (Object.keys(updateDoc).length > 0) bulkOps.push({ updateOne: {
+					filter: { id },
+					update: { $set: updateDoc }
+				} });
 			}
-			if (Object.keys(updateDoc).length > 0) bulkOps.push({ updateOne: {
-				filter: { id },
-				update: { $set: updateDoc }
-			} });
-		}
-		if (bulkOps.length > 0) await collection.bulkWrite(bulkOps);
-		if (threadIdsToUpdate.size > 0) await (await this.getCollection(TABLE_THREADS)).updateMany({ id: { $in: Array.from(threadIdsToUpdate) } }, { $set: { updatedAt: /* @__PURE__ */ new Date() } });
-		return (await collection.find({ id: { $in: messageIds } }).toArray()).map((row) => this.parseRow(row));
+			if (bulkOps.length > 0) await collection.bulkWrite(bulkOps, { session });
+			if (threadIdsToUpdate.size > 0) await (await this.getCollection(TABLE_THREADS)).updateMany({ id: { $in: Array.from(threadIdsToUpdate) } }, { $set: { updatedAt: /* @__PURE__ */ new Date() } }, { session });
+			return (await collection.find({ id: { $in: messageIds } }, { session }).toArray()).map((row) => this.parseRow(row));
+		});
 	}
 	async getResourceById({ resourceId }) {
 		try {
@@ -7153,9 +7440,11 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateResource({ resourceId, workingMemory, metadata }) {
+	async updateResource({ resourceId, workingMemory, metadata, fence }) {
 		try {
+			const check = this.#runFenceCheck(fence, "updateResource");
 			const existingResource = await this.getResourceById({ resourceId });
+			const collection = await this.getCollection(TABLE_RESOURCES);
 			if (!existingResource) {
 				const newResource = {
 					id: resourceId,
@@ -7164,7 +7453,11 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 					createdAt: /* @__PURE__ */ new Date(),
 					updatedAt: /* @__PURE__ */ new Date()
 				};
-				return this.saveResource({ resource: newResource });
+				await withRunFence(this.#connector, check, (session) => collection.updateOne({ id: resourceId }, { $set: { ...newResource } }, {
+					upsert: true,
+					session
+				}));
+				return newResource;
 			}
 			const updatedResource = {
 				...existingResource,
@@ -7175,13 +7468,13 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 				} : existingResource.metadata,
 				updatedAt: /* @__PURE__ */ new Date()
 			};
-			const collection = await this.getCollection(TABLE_RESOURCES);
 			const updateDoc = { updatedAt: updatedResource.updatedAt };
 			if (workingMemory !== void 0) updateDoc.workingMemory = workingMemory;
 			if (metadata) updateDoc.metadata = updatedResource.metadata;
-			await collection.updateOne({ id: resourceId }, { $set: updateDoc });
+			await withRunFence(this.#connector, check, (session) => collection.updateOne({ id: resourceId }, { $set: updateDoc }, { session }));
 			return updatedResource;
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "UPDATE_RESOURCE", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7281,14 +7574,19 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			throw mastraError;
 		}
 	}
-	async saveThread({ thread }) {
+	async saveThread({ thread, fence }) {
 		try {
-			await (await this.getCollection(TABLE_THREADS)).updateOne({ id: thread.id }, { $set: {
+			const collection = await this.getCollection(TABLE_THREADS);
+			await withRunFence(this.#connector, this.#runFenceCheck(fence, "saveThread"), (session) => collection.updateOne({ id: thread.id }, { $set: {
 				...thread,
 				metadata: thread.metadata
-			} }, { upsert: true });
+			} }, {
+				upsert: true,
+				session
+			}));
 			return thread;
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "SAVE_THREAD", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7297,7 +7595,8 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			}, error);
 		}
 	}
-	async updateThread({ id, title, metadata }) {
+	async updateThread({ id, title, metadata, fence }) {
+		const check = this.#runFenceCheck(fence, "updateThread");
 		const thread = await this.getThreadById({ threadId: id });
 		if (!thread) throw new MastraError({
 			id: createStorageErrorId("MONGODB", "UPDATE_THREAD", "NOT_FOUND"),
@@ -7320,12 +7619,14 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			updatedAt: now
 		};
 		try {
-			await (await this.getCollection(TABLE_THREADS)).updateOne({ id }, { $set: {
+			const collection = await this.getCollection(TABLE_THREADS);
+			await withRunFence(this.#connector, check, (session) => collection.updateOne({ id }, { $set: {
 				title: updatedThread.title,
 				metadata: updatedThread.metadata,
 				updatedAt: now
-			} });
+			} }, { session }));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "UPDATE_THREAD", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7348,16 +7649,19 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			}, error);
 		}
 	}
-	async deleteMessages(messageIds) {
+	async deleteMessages(messageIds, options) {
 		if (messageIds.length === 0) return;
 		try {
 			const messagesCollection = await this.getCollection(TABLE_MESSAGES);
 			const threadsCollection = await this.getCollection(TABLE_THREADS);
-			const messagesToDelete = await messagesCollection.find({ id: { $in: messageIds } }).toArray();
-			const threadIds = [...new Set(messagesToDelete.map((m) => m.thread_id))];
-			await messagesCollection.deleteMany({ id: { $in: messageIds } });
-			if (threadIds.length > 0) await threadsCollection.updateMany({ id: { $in: threadIds } }, { $set: { updatedAt: /* @__PURE__ */ new Date() } });
+			await withRunFence(this.#connector, this.#runFenceCheck(options?.fence, "deleteMessages"), async (session) => {
+				const messagesToDelete = await messagesCollection.find({ id: { $in: messageIds } }, { session }).toArray();
+				const threadIds = [...new Set(messagesToDelete.map((m) => m.thread_id))];
+				await messagesCollection.deleteMany({ id: { $in: messageIds } }, { session });
+				if (threadIds.length > 0) await threadsCollection.updateMany({ id: { $in: threadIds } }, { $set: { updatedAt: /* @__PURE__ */ new Date() } }, { session });
+			});
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "DELETE_MESSAGES", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7525,15 +7829,15 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			config: doc.config || {},
 			metadata: doc.metadata || void 0,
 			observedMessageIds: doc.observedMessageIds || void 0,
-			observedTimezone: doc.observedTimezone || void 0
+			observedTimezone: doc.observedTimezone || void 0,
+			supersededBy: doc.supersededBy ?? null
 		};
 	}
 	async getObservationalMemory(threadId, resourceId) {
 		try {
-			const lookupKey = this.getOMKey(threadId, resourceId);
-			const doc = await (await this.getCollection(OM_TABLE)).findOne({ lookupKey }, { sort: { generationCount: -1 } });
-			if (!doc) return null;
-			return this.parseOMDocument(doc);
+			const collection = await this.getCollection(OM_TABLE);
+			const doc = await this.#getHeadDoc(collection, this.getOMKey(threadId, resourceId));
+			return doc ? this.parseOMDocument(doc) : null;
 		} catch (error) {
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "GET_OBSERVATIONAL_MEMORY", "FAILED"),
@@ -7596,60 +7900,55 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	}
 	async initializeObservationalMemory(input) {
 		try {
+			const lookupKey = this.getOMKey(input.threadId, input.resourceId);
+			const collection = await this.getCollection(OM_TABLE);
+			const existing = await this.#getHeadDoc(collection, lookupKey);
+			if (existing) return this.parseOMDocument(existing);
 			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
-			};
-			await (await this.getCollection(OM_TABLE)).insertOne({
-				id,
-				lookupKey,
-				scope: input.scope,
-				resourceId: input.resourceId,
-				threadId: input.threadId || null,
-				activeObservations: "",
-				activeObservationsPendingUpdate: null,
-				originType: "initial",
-				config: input.config,
-				generationCount: 0,
-				lastObservedAt: null,
-				lastReflectionAt: null,
-				pendingMessageTokens: 0,
-				totalTokensObserved: 0,
-				observationTokenCount: 0,
-				isObserving: false,
-				isReflecting: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				observedTimezone: input.observedTimezone || null,
-				createdAt: now,
-				updatedAt: now
+			try {
+				await collection.insertOne({
+					_id: getGeneration0DocumentId(lookupKey),
+					id,
+					lookupKey,
+					scope: input.scope,
+					resourceId: input.resourceId,
+					threadId: input.threadId || null,
+					activeObservations: "",
+					activeObservationsPendingUpdate: null,
+					originType: "initial",
+					config: input.config,
+					generationCount: 0,
+					lastObservedAt: null,
+					lastReflectionAt: null,
+					pendingMessageTokens: 0,
+					totalTokensObserved: 0,
+					observationTokenCount: 0,
+					isObserving: false,
+					isReflecting: false,
+					isBufferingObservation: false,
+					isBufferingReflection: false,
+					lastBufferedAtTokens: 0,
+					lastBufferedAtTime: null,
+					observedTimezone: input.observedTimezone || null,
+					supersededBy: null,
+					createdAt: now,
+					updatedAt: now
+				});
+			} catch (error) {
+				if (!isDuplicateKeyError(error)) throw error;
+			}
+			const head = await this.#getHeadDoc(collection, lookupKey);
+			if (!head) throw new MastraError({
+				id: createStorageErrorId("MONGODB", "INITIALIZE_OBSERVATIONAL_MEMORY", "NOT_FOUND"),
+				text: `Observational memory record not found after initialization: ${id}`,
+				domain: ErrorDomain.STORAGE,
+				category: ErrorCategory.THIRD_PARTY,
+				details: { id }
 			});
-			return record;
+			return this.parseOMDocument(head);
 		} catch (error) {
+			if (error instanceof MastraError) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "INITIALIZE_OBSERVATIONAL_MEMORY", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7694,6 +7993,7 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 				lastBufferedAtTime: record.lastBufferedAtTime || null,
 				observedTimezone: record.observedTimezone || null,
 				metadata: record.metadata || null,
+				supersededBy: record.supersededBy ?? null,
 				createdAt: record.createdAt,
 				updatedAt: record.updatedAt
 			});
@@ -7711,28 +8011,40 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 		}
 	}
 	async updateActiveObservations(input) {
+		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
+	}
+	async commitActiveObservations(input) {
 		try {
-			const now = /* @__PURE__ */ new Date();
 			const collection = await this.getCollection(OM_TABLE);
 			const safeTokenCount = Number.isFinite(input.tokenCount) && input.tokenCount >= 0 ? input.tokenCount : 0;
-			const updateDoc = {
-				activeObservations: input.observations,
-				lastObservedAt: input.lastObservedAt,
-				pendingMessageTokens: 0,
-				observationTokenCount: safeTokenCount,
-				observedMessageIds: input.observedMessageIds ?? null,
-				updatedAt: now
-			};
-			if ((await collection.updateOne({ id: input.id }, {
-				$set: updateDoc,
-				$inc: { totalTokensObserved: safeTokenCount }
-			})).matchedCount === 0) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "UPDATE_ACTIVE_OBSERVATIONS", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.id}`,
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.THIRD_PARTY,
-				details: { id: input.id }
-			});
+			for (let attempt = 1; attempt <= OM_MAX_CONDITIONAL_ATTEMPTS; attempt++) {
+				const doc = await collection.findOne({ id: input.id });
+				if (!doc) throw omNotFound("UPDATE_ACTIVE_OBSERVATIONS", input.id);
+				if (doc.supersededBy) return {
+					applied: false,
+					reason: "retired"
+				};
+				if (input.expectedActiveObservations !== void 0 && input.expectedActiveObservations !== (doc.activeObservations || "")) return {
+					applied: false,
+					reason: "conflict"
+				};
+				if ((await withRunFence(this.#connector, this.#runFenceCheck(void 0, "updateActiveObservations"), (session) => collection.updateOne({
+					id: input.id,
+					supersededBy: null,
+					...matchStoredFields(doc, ["activeObservations", "lastObservedAt"])
+				}, {
+					$set: {
+						activeObservations: input.observations,
+						lastObservedAt: maxObservationCursor(doc.lastObservedAt, input.lastObservedAt),
+						pendingMessageTokens: 0,
+						observationTokenCount: safeTokenCount,
+						observedMessageIds: input.observedMessageIds ?? null,
+						updatedAt: /* @__PURE__ */ new Date()
+					},
+					$inc: { totalTokensObserved: safeTokenCount }
+				}, { session }))).matchedCount === 1) return { applied: true };
+			}
+			throw omConflict("UPDATE_ACTIVE_OBSERVATIONS", input.id);
 		} catch (error) {
 			if (error instanceof MastraError) throw error;
 			throw new MastraError({
@@ -7745,62 +8057,31 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	}
 	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
-			};
-			await (await this.getCollection(OM_TABLE)).insertOne({
-				id,
-				lookupKey,
-				scope: record.scope,
-				resourceId: record.resourceId,
-				threadId: record.threadId || null,
-				activeObservations: input.reflection,
-				activeObservationsPendingUpdate: null,
-				originType: "reflection",
-				config: record.config,
-				generationCount: input.currentRecord.generationCount + 1,
-				lastObservedAt: record.lastObservedAt || null,
-				lastReflectionAt: now,
-				pendingMessageTokens: record.pendingMessageTokens,
-				totalTokensObserved: record.totalTokensObserved,
-				observationTokenCount: record.observationTokenCount,
-				isObserving: false,
-				isReflecting: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				observedTimezone: record.observedTimezone || null,
-				createdAt: now,
-				updatedAt: now,
-				metadata: record.metadata || null
+			const { currentRecord } = input;
+			return await this.#rollOver(currentRecord, "createReflectionGeneration", (doc) => {
+				const stored = this.parseOMDocument(doc);
+				const plan = planReflectionGenerationText({
+					storedObservations: stored.activeObservations,
+					storedObservationTokenCount: stored.observationTokenCount,
+					snapshotObservations: currentRecord.activeObservations,
+					snapshotObservationTokenCount: currentRecord.observationTokenCount,
+					reflection: input.reflection,
+					tokenCount: input.tokenCount
+				});
+				if (!plan) return null;
+				return {
+					newId: input.newRecordId ?? globalThis.crypto.randomUUID(),
+					mode: plan.mode,
+					reflection: input.reflection,
+					tokenCount: input.tokenCount,
+					snapTextLength: (currentRecord.activeObservations ?? "").length,
+					snapObservationTokenCount: currentRecord.observationTokenCount ?? 0,
+					clearBufferedReflection: false,
+					createdAt: /* @__PURE__ */ new Date()
+				};
 			});
-			return record;
 		} catch (error) {
+			if (error instanceof MastraError) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "CREATE_REFLECTION_GENERATION", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -7867,23 +8148,12 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	}
 	async setBufferingObservationFlag(id, isBuffering, lastBufferedAtTokens) {
 		try {
-			const collection = await this.getCollection(OM_TABLE);
 			const updateDoc = {
 				isBufferingObservation: isBuffering,
 				updatedAt: /* @__PURE__ */ new Date()
 			};
 			if (lastBufferedAtTokens !== void 0) updateDoc.lastBufferedAtTokens = lastBufferedAtTokens;
-			if ((await collection.updateOne({ id }, { $set: updateDoc })).matchedCount === 0) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "SET_BUFFERING_OBSERVATION_FLAG", "NOT_FOUND"),
-				text: `Observational memory record not found: ${id}`,
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.THIRD_PARTY,
-				details: {
-					id,
-					isBuffering,
-					lastBufferedAtTokens: lastBufferedAtTokens ?? null
-				}
-			});
+			await this.#updateLiveDoc(id, "SET_BUFFERING_OBSERVATION_FLAG", { $set: updateDoc });
 		} catch (error) {
 			if (error instanceof MastraError) throw error;
 			throw new MastraError({
@@ -7954,19 +8224,10 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			}
 		});
 		try {
-			if ((await (await this.getCollection(OM_TABLE)).updateOne({ id }, { $set: {
+			await this.#updateLiveDoc(id, "SET_PENDING_MESSAGE_TOKENS", { $set: {
 				pendingMessageTokens: tokenCount,
 				updatedAt: /* @__PURE__ */ new Date()
-			} })).matchedCount === 0) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "SET_PENDING_MESSAGE_TOKENS", "NOT_FOUND"),
-				text: `Observational memory record not found: ${id}`,
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.THIRD_PARTY,
-				details: {
-					id,
-					tokenCount
-				}
-			});
+			} });
 		} catch (error) {
 			if (error instanceof MastraError) throw error;
 			throw new MastraError({
@@ -8008,6 +8269,9 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 		}
 	}
 	async updateBufferedObservations(input) {
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
 		try {
 			const collection = await this.getCollection(OM_TABLE);
 			const newChunk = {
@@ -8025,18 +8289,65 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 				extractedValues: input.chunk.extractedValues,
 				extractionFailures: input.chunk.extractionFailures
 			};
-			const setStage = {
-				updatedAt: /* @__PURE__ */ new Date(),
-				bufferedObservationChunks: { $concatArrays: [{ $ifNull: ["$bufferedObservationChunks", []] }, [newChunk]] }
-			};
-			if (input.lastBufferedAtTime) setStage.lastBufferedAtTime = input.lastBufferedAtTime;
-			if ((await collection.updateOne({ id: input.id }, [{ $set: setStage }])).matchedCount === 0) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "UPDATE_BUFFERED_OBSERVATIONS", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.id}`,
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.THIRD_PARTY,
-				details: { id: input.id }
-			});
+			const notCovered = { $or: [{ lastObservedAt: null }, { lastObservedAt: { $lt: /* @__PURE__ */ new Date(new Date(input.chunk.lastObservedAt).getTime() - 1) } }] };
+			const lastBufferedAtTime = input.lastBufferedAtTime ? new Date(input.lastBufferedAtTime) : void 0;
+			let targetId = input.id;
+			let hops = 0;
+			let retries = 0;
+			for (;;) {
+				if ((await withRunFence(this.#connector, this.#runFenceCheck(void 0, "updateBufferedObservations"), (session) => collection.updateOne({
+					id: targetId,
+					supersededBy: null,
+					"bufferedObservationChunks.cycleId": { $ne: input.chunk.cycleId },
+					...notCovered,
+					$and: [{ $or: [
+						{ bufferedObservationChunks: { $exists: false } },
+						{ bufferedObservationChunks: null },
+						{ bufferedObservationChunks: { $type: "array" } }
+					] }]
+				}, [{ $set: {
+					bufferedObservationChunks: { $concatArrays: [{ $ifNull: ["$bufferedObservationChunks", []] }, { $literal: [newChunk] }] },
+					...lastBufferedAtTime ? { lastBufferedAtTime: { $max: ["$lastBufferedAtTime", { $literal: lastBufferedAtTime }] } } : {},
+					updatedAt: { $literal: /* @__PURE__ */ new Date() }
+				} }], { session }))).matchedCount === 1) return {
+					persisted: true,
+					recordId: targetId
+				};
+				const doc = await collection.findOne({ id: targetId });
+				if (!doc) throw omNotFound("UPDATE_BUFFERED_OBSERVATIONS", targetId);
+				if (doc.supersededBy) {
+					const head = hops < OM_MAX_HEAD_HOPS ? await this.#getHeadDoc(collection, doc.lookupKey) : null;
+					if (!head || head.supersededBy || head.id === targetId) throw omNoLiveHead(input.id);
+					targetId = head.id;
+					hops++;
+					continue;
+				}
+				const stored = doc.bufferedObservationChunks;
+				if (Array.isArray(stored) && stored.some((c) => c?.cycleId === input.chunk.cycleId)) return {
+					persisted: false,
+					recordId: targetId
+				};
+				if (isBufferedChunkCoveredByCursor(input.chunk.lastObservedAt, doc.lastObservedAt)) return {
+					persisted: false,
+					recordId: targetId
+				};
+				if (stored !== void 0 && stored !== null && !Array.isArray(stored)) {
+					if ((await withRunFence(this.#connector, this.#runFenceCheck(void 0, "updateBufferedObservations"), (session) => collection.updateOne({
+						id: targetId,
+						supersededBy: null,
+						bufferedObservationChunks: stored,
+						...notCovered
+					}, { $set: {
+						bufferedObservationChunks: [newChunk],
+						...lastBufferedAtTime ? { lastBufferedAtTime: maxObservationCursor(doc.lastBufferedAtTime, lastBufferedAtTime) } : {},
+						updatedAt: /* @__PURE__ */ new Date()
+					} }, { session }))).matchedCount === 1) return {
+						persisted: true,
+						recordId: targetId
+					};
+				}
+				if (++retries >= OM_MAX_CONDITIONAL_ATTEMPTS) throw omConflict("UPDATE_BUFFERED_OBSERVATIONS", targetId);
+			}
 		} catch (error) {
 			if (error instanceof MastraError) throw error;
 			throw new MastraError({
@@ -8050,16 +8361,7 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	async swapBufferedToActive(input) {
 		try {
 			const collection = await this.getCollection(OM_TABLE);
-			const doc = await collection.findOne({ id: input.id });
-			if (!doc) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "SWAP_BUFFERED_TO_ACTIVE", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.id}`,
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.THIRD_PARTY,
-				details: { id: input.id }
-			});
-			const chunks = Array.isArray(doc.bufferedObservationChunks) ? doc.bufferedObservationChunks : [];
-			if (chunks.length === 0) return {
+			const emptyResult = {
 				chunksActivated: 0,
 				messageTokensActivated: 0,
 				observationTokensActivated: 0,
@@ -8067,95 +8369,107 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB 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;
+			for (let attempt = 1; attempt <= OM_MAX_CONDITIONAL_ATTEMPTS; attempt++) {
+				const doc = await collection.findOne({ id: input.id });
+				if (!doc) throw omNotFound("SWAP_BUFFERED_TO_ACTIVE", input.id);
+				if (doc.supersededBy) return {
+					...emptyResult,
+					retired: true
+				};
+				const persistedChunks = Array.isArray(doc.bufferedObservationChunks) ? doc.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 = 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((id) => !!id);
+				const activatedMessageIds = activatedChunks.flatMap((c) => c.messageIds ?? []);
+				const latestChunk = activatedChunks[activatedChunks.length - 1];
+				const lastObservedAt = input.lastObservedAt ?? (latestChunk?.lastObservedAt ? new Date(latestChunk.lastObservedAt) : /* @__PURE__ */ new Date());
+				const existingActive = doc.activeObservations || "";
+				const existingTokenCount = Number(doc.observationTokenCount || 0);
+				const boundary = `\n\n--- message boundary (${lastObservedAt.toISOString()}) ---\n\n`;
+				const newActive = existingActive ? `${existingActive}${boundary}${activatedContent}` : activatedContent;
+				const newTokenCount = existingTokenCount + activatedTokens;
+				const existingPending = Number(doc.pendingMessageTokens || 0);
+				const newPending = Math.max(0, existingPending - activatedMessageTokens);
+				if ((await withRunFence(this.#connector, this.#runFenceCheck(void 0, "swapBufferedToActive"), (session) => collection.updateOne({
+					id: input.id,
+					supersededBy: null,
+					...matchStoredFields(doc, [
+						"bufferedObservationChunks",
+						"activeObservations",
+						"observationTokenCount",
+						"pendingMessageTokens",
+						"lastObservedAt"
+					])
+				}, { $set: {
+					activeObservations: newActive,
+					observationTokenCount: newTokenCount,
+					pendingMessageTokens: newPending,
+					bufferedObservationChunks: remainingChunks,
+					lastObservedAt: maxObservationCursor(doc.lastObservedAt, lastObservedAt),
+					updatedAt: /* @__PURE__ */ new Date()
+				} }, { session }))).matchedCount === 0) continue;
+				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 = 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((id) => !!id);
-			const activatedMessageIds = activatedChunks.flatMap((c) => c.messageIds ?? []);
-			const latestChunk = activatedChunks[activatedChunks.length - 1];
-			const lastObservedAt = input.lastObservedAt ?? (latestChunk?.lastObservedAt ? new Date(latestChunk.lastObservedAt) : /* @__PURE__ */ new Date());
-			const existingActive = doc.activeObservations || "";
-			const existingTokenCount = Number(doc.observationTokenCount || 0);
-			const boundary = `\n\n--- message boundary (${lastObservedAt.toISOString()}) ---\n\n`;
-			const newActive = existingActive ? `${existingActive}${boundary}${activatedContent}` : activatedContent;
-			const newTokenCount = existingTokenCount + activatedTokens;
-			const existingPending = Number(doc.pendingMessageTokens || 0);
-			const newPending = Math.max(0, existingPending - activatedMessageTokens);
-			if ((await collection.updateOne({
-				id: input.id,
-				bufferedObservationChunks: {
-					$exists: true,
-					$ne: null,
-					$not: { $size: 0 }
-				}
-			}, { $set: {
-				activeObservations: newActive,
-				observationTokenCount: newTokenCount,
-				pendingMessageTokens: newPending,
-				bufferedObservationChunks: remainingChunks,
-				lastObservedAt,
-				updatedAt: /* @__PURE__ */ new Date()
-			} })).modifiedCount === 0) return {
-				chunksActivated: 0,
-				messageTokensActivated: 0,
-				observationTokensActivated: 0,
-				messagesActivated: 0,
-				activatedCycleIds: [],
-				activatedMessageIds: []
-			};
-			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
-			};
+			throw omConflict("SWAP_BUFFERED_TO_ACTIVE", input.id);
 		} catch (error) {
 			if (error instanceof MastraError) throw error;
 			throw new MastraError({
@@ -8183,13 +8497,13 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			const newContent = existingContent ? `${existingContent}\n\n${input.reflection}` : input.reflection;
 			const newTokens = existingTokens + input.tokenCount;
 			const newInputTokens = existingInputTokens + input.inputTokenCount;
-			if ((await collection.updateOne({ id: input.id }, { $set: {
+			if ((await withRunFence(this.#connector, this.#runFenceCheck(void 0, "updateBufferedReflection"), (session) => collection.updateOne({ id: input.id }, { $set: {
 				bufferedReflection: newContent,
 				bufferedReflectionTokens: newTokens,
 				bufferedReflectionInputTokens: newInputTokens,
 				reflectedObservationLineCount: input.reflectedObservationLineCount,
 				updatedAt: /* @__PURE__ */ new Date()
-			} })).matchedCount === 0) throw new MastraError({
+			} }, { session }))).matchedCount === 0) throw new MastraError({
 				id: createStorageErrorId("MONGODB", "UPDATE_BUFFERED_REFLECTION", "NOT_FOUND"),
 				text: `Observational memory record not found: ${input.id}`,
 				domain: ErrorDomain.STORAGE,
@@ -8208,39 +8522,33 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 	}
 	async swapBufferedReflectionToActive(input) {
 		try {
-			const collection = await this.getCollection(OM_TABLE);
-			const doc = await collection.findOne({ id: input.currentRecord.id });
-			if (!doc) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.currentRecord.id}`,
-				domain: ErrorDomain.STORAGE,
-				category: ErrorCategory.THIRD_PARTY,
-				details: { id: input.currentRecord.id }
-			});
-			const bufferedReflection = doc.bufferedReflection || "";
-			const reflectedLineCount = Number(doc.reflectedObservationLineCount || 0);
-			if (!bufferedReflection) throw new MastraError({
-				id: createStorageErrorId("MONGODB", "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 = (doc.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.#rollOver(currentRecord, "swapBufferedReflectionToActive", (doc) => {
+				const stored = this.parseOMDocument(doc);
+				const bufferedReflection = stored.bufferedReflection || "";
+				if (!bufferedReflection) throw new MastraError({
+					id: createStorageErrorId("MONGODB", "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 null;
+				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 {
+					newId: input.newRecordId ?? globalThis.crypto.randomUUID(),
+					mode: "equal",
+					reflection: newObservations,
+					tokenCount,
+					snapTextLength: (stored.activeObservations ?? "").length,
+					snapObservationTokenCount: stored.observationTokenCount ?? 0,
+					clearBufferedReflection: true,
+					createdAt: /* @__PURE__ */ new Date()
+				};
 			});
-			await collection.updateOne({ id: input.currentRecord.id }, { $set: {
-				bufferedReflection: null,
-				bufferedReflectionTokens: null,
-				bufferedReflectionInputTokens: null,
-				reflectedObservationLineCount: null,
-				updatedAt: /* @__PURE__ */ new Date()
-			} });
-			return newRecord;
 		} catch (error) {
 			if (error instanceof MastraError) throw error;
 			throw new MastraError({
@@ -8251,6 +8559,171 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends MemoryStorage {
 			}, error);
 		}
 	}
+	/**
+	* The head of a lookup key by the canonical order (`generationCount DESC, createdAt ASC, id ASC`).
+	* A head that was fenced for rollover but whose successor insert never ran (crash, or still in
+	* flight in another process) is rolled forward here, so every head read reaches the successor.
+	*/
+	async #getHeadDoc(collection, lookupKey) {
+		for (let hop = 0; hop <= OM_MAX_HEAD_HOPS; hop++) {
+			const head = await collection.findOne({ lookupKey }, { sort: OM_HEAD_SORT });
+			if (!head || !head.supersededBy || !head.pendingSuccessor) return head;
+			await this.#completeRollover(collection, head, head.pendingSuccessor);
+		}
+		throw omNoLiveHead(lookupKey);
+	}
+	/**
+	* A single-document update aimed at a live record. A retired (or concurrently fenced) id is
+	* redirected to the head, at most `OM_MAX_HEAD_HOPS` times.
+	*/
+	async #updateLiveDoc(id, operation, update) {
+		const collection = await this.getCollection(OM_TABLE);
+		let targetId = id;
+		for (let hop = 0; hop <= OM_MAX_HEAD_HOPS; hop++) {
+			if ((await collection.updateOne({
+				id: targetId,
+				supersededBy: null
+			}, update)).matchedCount === 1) return targetId;
+			const doc = await collection.findOne({ id: targetId }, { projection: {
+				lookupKey: 1,
+				supersededBy: 1
+			} });
+			if (!doc) throw omNotFound(operation, targetId);
+			if (!doc.supersededBy) continue;
+			const head = await this.#getHeadDoc(collection, doc.lookupKey);
+			if (!head || head.supersededBy || head.id === targetId) throw omNoLiveHead(id);
+			targetId = head.id;
+		}
+		throw omNoLiveHead(id);
+	}
+	/**
+	* Roll the live record `currentRecord.id` over to a new generation.
+	*
+	* 1. Read the stored document and decide (`decide` returns the successor inputs, or `null`
+	*    when the snapshot is stale).
+	* 2. Fence: one conditional update sets `supersededBy` and the small `pendingSuccessor`
+	*    payload, matching only if the fields the decision read are unchanged. From here the old
+	*    document is frozen — no lifecycle write matches it — so its pre-image is its final state.
+	* 3. Insert the successor built purely from that pre-image, then clear the old document's
+	*    chunks (they moved) and `pendingSuccessor`.
+	*
+	* A crash between 2 and 3 is finished by the next head read (`#getHeadDoc`) or startup.
+	*/
+	async #rollOver(currentRecord, operation, decide) {
+		const collection = await this.getCollection(OM_TABLE);
+		for (let attempt = 1; attempt <= OM_MAX_CONDITIONAL_ATTEMPTS; attempt++) {
+			const doc = await collection.findOne({ id: currentRecord.id });
+			if (!doc) return currentRecord;
+			if (doc.supersededBy) {
+				const head = await this.#getHeadDoc(collection, doc.lookupKey);
+				return head ? this.parseOMDocument(head) : currentRecord;
+			}
+			const pending = decide(doc);
+			if (!pending) return this.parseOMDocument(doc);
+			const frozen = await withRunFence(this.#connector, this.#runFenceCheck(void 0, operation), (session) => collection.findOneAndUpdate({
+				id: doc.id,
+				supersededBy: null,
+				...matchStoredFields(doc, [
+					"activeObservations",
+					"observationTokenCount",
+					"bufferedReflection",
+					"reflectedObservationLineCount"
+				])
+			}, { $set: {
+				supersededBy: pending.newId,
+				pendingSuccessor: pending
+			} }, {
+				returnDocument: "before",
+				session
+			}));
+			if (!frozen) continue;
+			return this.parseOMDocument(await this.#completeRollover(collection, frozen, pending));
+		}
+		throw omConflict("CREATE_REFLECTION_GENERATION", currentRecord.id);
+	}
+	/** Insert the successor of a fenced document (idempotent) and clean up the old document. */
+	async #completeRollover(collection, frozen, pending) {
+		try {
+			await collection.insertOne(buildSuccessorDocument(frozen, pending));
+		} catch (error) {
+			if (!isDuplicateKeyError(error)) throw error;
+		}
+		await collection.updateOne({
+			id: frozen.id,
+			supersededBy: pending.newId
+		}, {
+			$set: {
+				bufferedObservationChunks: [],
+				...pending.clearBufferedReflection ? {
+					bufferedReflection: null,
+					bufferedReflectionTokens: null,
+					bufferedReflectionInputTokens: null,
+					reflectedObservationLineCount: null
+				} : {},
+				updatedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: { pendingSuccessor: "" }
+		});
+		const successor = await collection.findOne({ id: pending.newId });
+		if (!successor) throw omNotFound("CREATE_REFLECTION_GENERATION", pending.newId);
+		return successor;
+	}
+	/**
+	* Startup maintenance for the `supersededBy` marker:
+	* - finish rollovers interrupted after the fence (insert the successor if missing, clean up);
+	* - for keys with more than one live document (left by older adapter versions, which never set
+	*   `supersededBy`), retire every live document that sorts after the canonical head. The head's
+	*   ordering key is embedded in the filter, so a document created by a concurrent rollover
+	*   (a newer generation) never matches.
+	*/
+	async #maintainSupersededBy() {
+		const collection = await this.getCollection(OM_TABLE);
+		const interrupted = await collection.find({
+			supersededBy: { $nin: [null] },
+			pendingSuccessor: { $exists: true }
+		}).toArray();
+		for (const doc of interrupted) await this.#completeRollover(collection, doc, doc.pendingSuccessor);
+		const keys = await collection.aggregate([
+			{ $match: { supersededBy: null } },
+			{ $group: {
+				_id: "$lookupKey",
+				live: { $sum: 1 }
+			} },
+			{ $match: { live: { $gt: 1 } } }
+		]).toArray();
+		for (const { _id: lookupKey } of keys) {
+			const head = await this.#getHeadDoc(collection, lookupKey);
+			if (!head || head.supersededBy) continue;
+			await collection.updateMany({
+				lookupKey,
+				supersededBy: null,
+				$or: [
+					{ generationCount: { $lt: head.generationCount } },
+					{
+						generationCount: head.generationCount,
+						createdAt: { $gt: head.createdAt }
+					},
+					{
+						generationCount: head.generationCount,
+						createdAt: head.createdAt,
+						id: { $gt: head.id }
+					}
+				]
+			}, { $set: { supersededBy: head.id } });
+		}
+	}
+	/**
+	* Cross-process rollover and initialization rely on the unique `id` index (a duplicate insert
+	* of the same successor or generation-0 id must fail). Warn once if it is missing, e.g. under
+	* `skipDefaultIndexes`.
+	*/
+	async #warnIfOMIdIndexMissing() {
+		try {
+			if (!(await (await this.getCollection(OM_TABLE)).listIndexes().toArray().catch((error) => error?.code === 26 ? [] : Promise.reject(error))).some((index) => index.unique && Object.keys(index.key ?? {}).length === 1 && index.key.id === 1)) this.logger?.warn?.(`MongoDB collection "${OM_TABLE}" has no unique index on { id: 1 }. Observational memory needs it to stay consistent when several processes write the same thread or resource. Create it with db.${OM_TABLE}.createIndex({ id: 1 }, { unique: true }).`);
+		} catch (error) {
+			this.logger?.warn?.(`Could not list indexes on MongoDB collection "${OM_TABLE}":`, error);
+		}
+	}
 };
 //#endregion
 //#region src/storage/domains/notifications/index.ts
@@ -11477,33 +11950,58 @@ var MongoDBWorkflowDefinitionsStore = class MongoDBWorkflowDefinitionsStore exte
 };
 //#endregion
 //#region src/storage/domains/workflows/index.ts
+const RUN_OWNER_PROJECTION = {
+	generation: 1,
+	ownerId: 1,
+	leaseExpiresAt: 1,
+	live: { $gt: ["$leaseExpiresAt", "$$NOW"] }
+};
+const NOT_LIVE = { $or: [{ leaseExpiresAt: null }, { $expr: { $lte: ["$leaseExpiresAt", "$$NOW"] } }] };
+function toRunOwnershipRecord(doc) {
+	return {
+		runId: doc._id,
+		generation: Number(doc.generation),
+		ownerId: doc.ownerId,
+		leaseExpiresAt: doc.leaseExpiresAt ?? null,
+		live: Boolean(doc.live)
+	};
+}
 var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsStorage {
 	#connector;
 	#skipDefaultIndexes;
 	#indexes;
 	/** Collections managed by this domain */
-	static MANAGED_COLLECTIONS = [TABLE_WORKFLOW_SNAPSHOT];
+	static MANAGED_COLLECTIONS = [TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKFLOW_RUN_OWNERS];
 	/**
-	* Anchor is `updatedAt` (BSON date), so the policy reads as inactivity:
-	* a run is pruned only after its snapshot has not been touched for `maxAge`.
+	* Both anchors are `updatedAt` (BSON date), so the policies read as
+	* inactivity: a run is pruned only after its snapshot has not been touched
+	* for `maxAge`, and an ownership document only after no claim, renewal or
+	* release has touched it for `maxAge`.
 	*/
-	static retentionTables = { workflowSnapshot: {
-		table: TABLE_WORKFLOW_SNAPSHOT,
-		column: "updatedAt",
-		indexed: true
-	} };
+	static retentionTables = {
+		workflowSnapshot: {
+			table: TABLE_WORKFLOW_SNAPSHOT,
+			column: "updatedAt",
+			indexed: true
+		},
+		runOwnership: {
+			table: TABLE_WORKFLOW_RUN_OWNERS,
+			column: "updatedAt",
+			indexed: true
+		}
+	};
 	constructor(config) {
 		super();
 		this.#connector = resolveMongoDBConfig(config);
 		this.#skipDefaultIndexes = config.skipDefaultIndexes;
 		this.#indexes = config.indexes?.filter((idx) => WorkflowsStorageMongoDB.MANAGED_COLLECTIONS.includes(idx.collection));
 	}
-	/** Delete workflow snapshots idle for longer than the policy's `maxAge`, batched. */
+	/** Delete workflow snapshots and ownership documents idle for longer than each policy's `maxAge`, batched. */
 	async prune(policies, options) {
 		const targets = resolveTargets({
 			policies,
 			descriptor: WorkflowsStorageMongoDB.retentionTables,
-			order: ["workflowSnapshot"]
+			order: ["workflowSnapshot", "runOwnership"]
 		});
 		return runPrune({
 			connector: this.#connector,
@@ -11516,6 +12014,13 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 	supportsConcurrentUpdates() {
 		return true;
 	}
+	/**
+	* Fenced writes need multi-document transactions, so only replica sets and
+	* sharded clusters fence. Rejects while the deployment can't be probed.
+	*/
+	supportsRunFencing() {
+		return this.#connector.probeTransactions();
+	}
 	async getCollection(name) {
 		return this.#connector.getCollection(name);
 	}
@@ -11523,6 +12028,124 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
 	}
+	#runFenceCheck(fence, runId, operation) {
+		const resolved = resolveRunFence(this, fence, runId);
+		return resolved && {
+			claims: TABLE_WORKFLOW_RUN_OWNERS,
+			fence: resolved,
+			operation
+		};
+	}
+	async #readRunOwner(runId) {
+		const doc = await (await getRunClaims(this.#connector, TABLE_WORKFLOW_RUN_OWNERS)).findOne({ _id: runId }, { projection: RUN_OWNER_PROJECTION });
+		return doc ? toRunOwnershipRecord(doc) : null;
+	}
+	#ownershipError(operation, runId, error) {
+		return new MastraError({
+			id: createStorageErrorId("MONGODB", operation, "FAILED"),
+			domain: ErrorDomain.STORAGE,
+			category: ErrorCategory.THIRD_PARTY,
+			details: { runId }
+		}, error);
+	}
+	async claimRunOwnership({ runId, ownerId, leaseMs, force, expectedGeneration }) {
+		try {
+			const owners = await getRunClaims(this.#connector, TABLE_WORKFLOW_RUN_OWNERS);
+			const claim = (generation) => [{ $set: {
+				generation,
+				ownerId: { $literal: ownerId },
+				leaseExpiresAt: { $add: ["$$NOW", leaseMs] },
+				updatedAt: "$$NOW"
+			} }];
+			if (!expectedGeneration) {
+				try {
+					const created = await owners.findOneAndUpdate({
+						_id: runId,
+						generation: { $exists: false }
+					}, claim({ $max: [1, { $toLong: "$$NOW" }] }), {
+						upsert: true,
+						returnDocument: "after",
+						projection: RUN_OWNER_PROJECTION
+					});
+					if (created) return {
+						acquired: true,
+						record: toRunOwnershipRecord(created)
+					};
+				} catch (error) {
+					if (!isDuplicateKeyError(error)) throw error;
+				}
+				if (expectedGeneration === 0) return {
+					acquired: false,
+					record: await this.#readRunOwner(runId)
+				};
+			}
+			const advanced = await owners.findOneAndUpdate({
+				_id: runId,
+				...expectedGeneration !== void 0 ? { generation: expectedGeneration } : {},
+				...force ? {} : NOT_LIVE
+			}, claim({ $add: ["$generation", 1] }), {
+				returnDocument: "after",
+				projection: RUN_OWNER_PROJECTION
+			});
+			if (advanced) return {
+				acquired: true,
+				record: toRunOwnershipRecord(advanced)
+			};
+			return {
+				acquired: false,
+				record: await this.#readRunOwner(runId)
+			};
+		} catch (error) {
+			throw this.#ownershipError("CLAIM_RUN_OWNERSHIP", runId, error);
+		}
+	}
+	async renewRunOwnership({ leaseMs, ...fence }) {
+		try {
+			const renewed = await (await getRunClaims(this.#connector, TABLE_WORKFLOW_RUN_OWNERS)).findOneAndUpdate({
+				_id: fence.runId,
+				generation: fence.generation,
+				ownerId: fence.ownerId,
+				leaseExpiresAt: { $ne: null }
+			}, [{ $set: {
+				leaseExpiresAt: { $add: ["$$NOW", leaseMs] },
+				updatedAt: "$$NOW"
+			} }], {
+				returnDocument: "after",
+				projection: RUN_OWNER_PROJECTION
+			});
+			if (renewed) return {
+				renewed: true,
+				record: toRunOwnershipRecord(renewed)
+			};
+			return {
+				renewed: false,
+				record: await this.#readRunOwner(fence.runId)
+			};
+		} catch (error) {
+			throw this.#ownershipError("RENEW_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async releaseRunOwnership(fence) {
+		try {
+			return (await (await getRunClaims(this.#connector, TABLE_WORKFLOW_RUN_OWNERS)).updateOne({
+				_id: fence.runId,
+				generation: fence.generation,
+				ownerId: fence.ownerId
+			}, [{ $set: {
+				leaseExpiresAt: null,
+				updatedAt: "$$NOW"
+			} }])).matchedCount > 0;
+		} catch (error) {
+			throw this.#ownershipError("RELEASE_RUN_OWNERSHIP", fence.runId, error);
+		}
+	}
+	async getRunOwnership({ runId }) {
+		try {
+			return await this.#readRunOwner(runId);
+		} catch (error) {
+			throw this.#ownershipError("GET_RUN_OWNERSHIP", runId, error);
+		}
+	}
 	/**
 	* Returns default index definitions for the workflows domain collections.
 	*/
@@ -11582,8 +12205,10 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 	}
 	async dangerouslyClearAll() {
 		await (await this.getCollection(TABLE_WORKFLOW_SNAPSHOT)).deleteMany({});
+		await (await this.getCollection(TABLE_WORKFLOW_RUN_OWNERS)).deleteMany({});
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state, fence }) {
+		const check = this.#runFenceCheck(fence, runId, "updateWorkflowResults");
 		try {
 			const collection = await this.getCollection(TABLE_WORKFLOW_SNAPSHOT);
 			const now = /* @__PURE__ */ new Date();
@@ -11603,7 +12228,7 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 				runId,
 				requestContext: {}
 			};
-			const updatedDoc = await collection.findOneAndUpdate({
+			const updatedDoc = await withRunFence(this.#connector, check, (session) => collection.findOneAndUpdate({
 				workflow_name: workflowName,
 				run_id: runId
 			}, [{ $set: {
@@ -11618,10 +12243,12 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 				createdAt: { $ifNull: ["$createdAt", now] }
 			} }], {
 				upsert: true,
-				returnDocument: "after"
-			});
+				returnDocument: "after",
+				session
+			}));
 			return (typeof updatedDoc?.snapshot === "string" ? JSON.parse(updatedDoc.snapshot) : updatedDoc?.snapshot)?.context || {};
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "UPDATE_WORKFLOW_RESULTS", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11634,7 +12261,8 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 			}, error);
 		}
 	}
-	async updateWorkflowState({ workflowName, runId, opts }) {
+	async updateWorkflowState({ workflowName, runId, opts, fence }) {
+		const check = this.#runFenceCheck(fence, runId, "updateWorkflowState");
 		try {
 			const collection = await this.getCollection(TABLE_WORKFLOW_SNAPSHOT);
 			const { expectedStatus, ...state } = opts;
@@ -11643,10 +12271,13 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 				run_id: runId
 			};
 			if (expectedStatus !== void 0) filter["snapshot.status"] = { $in: Array.isArray(expectedStatus) ? expectedStatus : [expectedStatus] };
-			const updatedDoc = await collection.findOneAndUpdate(filter, [{ $set: {
+			const updatedDoc = await withRunFence(this.#connector, check, (session) => collection.findOneAndUpdate(filter, [{ $set: {
 				snapshot: { $mergeObjects: ["$snapshot", state] },
 				updatedAt: /* @__PURE__ */ new Date()
-			} }], { returnDocument: "after" });
+			} }], {
+				returnDocument: "after",
+				session
+			}));
 			if (!updatedDoc) return;
 			const snapshot = typeof updatedDoc.snapshot === "string" ? JSON.parse(updatedDoc.snapshot) : updatedDoc.snapshot;
 			if (!snapshot?.context) throw new MastraError({
@@ -11661,7 +12292,7 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 			});
 			return snapshot;
 		} catch (error) {
-			if (error instanceof MastraError) throw error;
+			if (error instanceof MastraError || isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "UPDATE_WORKFLOW_STATE", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11673,10 +12304,12 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 			}, error);
 		}
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
+		const check = this.#runFenceCheck(fence, runId, "persistWorkflowSnapshot");
 		try {
 			const now = /* @__PURE__ */ new Date();
-			await (await this.getCollection(TABLE_WORKFLOW_SNAPSHOT)).updateOne({
+			const collection = await this.getCollection(TABLE_WORKFLOW_SNAPSHOT);
+			await withRunFence(this.#connector, check, (session) => collection.updateOne({
 				workflow_name: workflowName,
 				run_id: runId
 			}, {
@@ -11688,8 +12321,12 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 					updatedAt: updatedAt ?? now
 				},
 				$setOnInsert: { createdAt: createdAt ?? now }
-			}, { upsert: true });
+			}, {
+				upsert: true,
+				session
+			}));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "PERSIST_WORKFLOW_SNAPSHOT", "FAILED"),
 				domain: ErrorDomain.STORAGE,
@@ -11782,13 +12419,16 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends WorkflowsSto
 			}, error);
 		}
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
+		const check = this.#runFenceCheck(fence, runId, "deleteWorkflowRunById");
 		try {
-			await (await this.getCollection(TABLE_WORKFLOW_SNAPSHOT)).deleteOne({
+			const collection = await this.getCollection(TABLE_WORKFLOW_SNAPSHOT);
+			await withRunFence(this.#connector, check, (session) => collection.deleteOne({
 				workflow_name: workflowName,
 				run_id: runId
-			});
+			}, { session }));
 		} catch (error) {
+			if (isRunFenceConflictError(error)) throw error;
 			throw new MastraError({
 				id: createStorageErrorId("MONGODB", "DELETE_WORKFLOW_RUN_BY_ID", "FAILED"),
 				domain: ErrorDomain.STORAGE,