@mastra/mongodb 1.23.0-alpha.1 → 1.23.1-alpha.0

package/dist/index.cjs

@@ -5,11 +5,12 @@ let _mastra_core_storage = require("@mastra/core/storage");
 let _mastra_core_vector = require("@mastra/core/vector");
 let mongodb = require("mongodb");
 let _mastra_core_vector_filter = require("@mastra/core/vector/filter");
+let crypto$1 = require("crypto");
 let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_evals = require("@mastra/core/evals");
 let _mastra_core_storage_domains_skills = require("@mastra/core/storage/domains/skills");
 //#region package.json
-var version = "1.23.0-alpha.1";
+var version = "1.23.1-alpha.0";
 //#endregion
 //#region src/vector/filter.ts
 /**
@@ -6495,6 +6496,71 @@ var MongoDBMCPServersStorage = class MongoDBMCPServersStorage extends _mastra_co
 	}
 };
 //#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/memory/index.ts
 /**
 * Local constant for the observational memory table name.
@@ -6502,6 +6568,98 @@ var MongoDBMCPServersStorage = class MongoDBMCPServersStorage extends _mastra_co
 * 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_${(0, crypto$1.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 isDuplicateKeyError(error) {
+	return error?.code === 11e3;
+}
+function omNotFound(operation, id) {
+	return new _mastra_core_error.MastraError({
+		id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", operation, "NOT_FOUND"),
+		text: `Observational memory record not found: ${id}`,
+		domain: _mastra_core_error.ErrorDomain.STORAGE,
+		category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+		details: { id }
+	});
+}
+function omConflict(operation, id) {
+	return new _mastra_core_error.MastraError({
+		id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", operation, "CONFLICT"),
+		text: `Observational memory record ${id} kept changing during ${operation}; giving up after ${OM_MAX_CONDITIONAL_ATTEMPTS} attempts`,
+		domain: _mastra_core_error.ErrorDomain.STORAGE,
+		category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+		details: { id }
+	});
+}
+function omNoLiveHead(id) {
+	return new _mastra_core_error.MastraError({
+		id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "RESOLVE_OBSERVATIONAL_MEMORY_HEAD", "FAILED"),
+		text: `Observational memory record ${id} is superseded but no live head was found`,
+		domain: _mastra_core_error.ErrorDomain.STORAGE,
+		category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+		details: { id }
+	});
+}
 var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_storage.MemoryStorage {
 	supportsPartialThreadUpdate = true;
 	supportsObservationalMemory = true;
@@ -6549,6 +6707,8 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 	async init() {
 		await this.createDefaultIndexes();
 		await this.createCustomIndexes();
+		await this.#warnIfOMIdIndexMissing();
+		await this.#maintainSupersededBy();
 	}
 	/**
 	* Delete memory rows older than each table's `maxAge`, batched. Order is
@@ -7526,15 +7686,15 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 			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 _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "GET_OBSERVATIONAL_MEMORY", "FAILED"),
@@ -7597,60 +7757,55 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 	}
 	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 _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "INITIALIZE_OBSERVATIONAL_MEMORY", "NOT_FOUND"),
+				text: `Observational memory record not found after initialization: ${id}`,
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { id }
 			});
-			return record;
+			return this.parseOMDocument(head);
 		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "INITIALIZE_OBSERVATIONAL_MEMORY", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -7695,6 +7850,7 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 				lastBufferedAtTime: record.lastBufferedAtTime || null,
 				observedTimezone: record.observedTimezone || null,
 				metadata: record.metadata || null,
+				supersededBy: record.supersededBy ?? null,
 				createdAt: record.createdAt,
 				updatedAt: record.updatedAt
 			});
@@ -7712,28 +7868,40 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 		}
 	}
 	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 _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "UPDATE_ACTIVE_OBSERVATIONS", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.id}`,
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.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 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 }
+				})).matchedCount === 1) return { applied: true };
+			}
+			throw omConflict("UPDATE_ACTIVE_OBSERVATIONS", input.id);
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -7746,62 +7914,31 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 	}
 	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, (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 _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "CREATE_REFLECTION_GENERATION", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -7868,23 +8005,12 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 	}
 	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 _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "SET_BUFFERING_OBSERVATION_FLAG", "NOT_FOUND"),
-				text: `Observational memory record not found: ${id}`,
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
-				details: {
-					id,
-					isBuffering,
-					lastBufferedAtTokens: lastBufferedAtTokens ?? null
-				}
-			});
+			await this.#updateLiveDoc(id, "SET_BUFFERING_OBSERVATION_FLAG", { $set: updateDoc });
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -7955,19 +8081,10 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 			}
 		});
 		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 _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "SET_PENDING_MESSAGE_TOKENS", "NOT_FOUND"),
-				text: `Observational memory record not found: ${id}`,
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
-				details: {
-					id,
-					tokenCount
-				}
-			});
+			} });
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -8009,6 +8126,9 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 		}
 	}
 	async updateBufferedObservations(input) {
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
 		try {
 			const collection = await this.getCollection(OM_TABLE);
 			const newChunk = {
@@ -8026,18 +8146,65 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 				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 _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "UPDATE_BUFFERED_OBSERVATIONS", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.id}`,
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.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 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() }
+				} }])).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 collection.updateOne({
+						id: targetId,
+						supersededBy: null,
+						bufferedObservationChunks: stored,
+						...notCovered
+					}, { $set: {
+						bufferedObservationChunks: [newChunk],
+						...lastBufferedAtTime ? { lastBufferedAtTime: maxObservationCursor(doc.lastBufferedAtTime, lastBufferedAtTime) } : {},
+						updatedAt: /* @__PURE__ */ new Date()
+					} })).matchedCount === 1) return {
+						persisted: true,
+						recordId: targetId
+					};
+				}
+				if (++retries >= OM_MAX_CONDITIONAL_ATTEMPTS) throw omConflict("UPDATE_BUFFERED_OBSERVATIONS", targetId);
+			}
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -8051,16 +8218,7 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 	async swapBufferedToActive(input) {
 		try {
 			const collection = await this.getCollection(OM_TABLE);
-			const doc = await collection.findOne({ id: input.id });
-			if (!doc) throw new _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "SWAP_BUFFERED_TO_ACTIVE", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.id}`,
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.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,
@@ -8068,95 +8226,107 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 				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 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()
+				} })).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 _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -8209,39 +8379,33 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 	}
 	async swapBufferedReflectionToActive(input) {
 		try {
-			const collection = await this.getCollection(OM_TABLE);
-			const doc = await collection.findOne({ id: input.currentRecord.id });
-			if (!doc) throw new _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NOT_FOUND"),
-				text: `Observational memory record not found: ${input.currentRecord.id}`,
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
-				details: { id: input.currentRecord.id }
-			});
-			const bufferedReflection = doc.bufferedReflection || "";
-			const reflectedLineCount = Number(doc.reflectedObservationLineCount || 0);
-			if (!bufferedReflection) throw new _mastra_core_error.MastraError({
-				id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NO_CONTENT"),
-				text: "No buffered reflection to swap",
-				domain: _mastra_core_error.ErrorDomain.STORAGE,
-				category: _mastra_core_error.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, (doc) => {
+				const stored = this.parseOMDocument(doc);
+				const bufferedReflection = stored.bufferedReflection || "";
+				if (!bufferedReflection) throw new _mastra_core_error.MastraError({
+					id: (0, _mastra_core_storage.createStorageErrorId)("MONGODB", "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NO_CONTENT"),
+					text: "No buffered reflection to swap",
+					domain: _mastra_core_error.ErrorDomain.STORAGE,
+					category: _mastra_core_error.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 _mastra_core_error.MastraError) throw error;
 			throw new _mastra_core_error.MastraError({
@@ -8252,6 +8416,168 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 			}, 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, 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 collection.findOneAndUpdate({
+				id: doc.id,
+				supersededBy: null,
+				...matchStoredFields(doc, [
+					"activeObservations",
+					"observationTokenCount",
+					"bufferedReflection",
+					"reflectedObservationLineCount"
+				])
+			}, { $set: {
+				supersededBy: pending.newId,
+				pendingSuccessor: pending
+			} }, { returnDocument: "before" });
+			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