@mastra/oracledb 0.5.1 → 0.5.2-alpha.1

package/dist/index.cjs

@@ -3369,6 +3369,124 @@ function jsonComparableValue$1(value) {
 	return value;
 }
 //#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/db/run-fencing.ts
+const SINCE_EPOCH = `(SYS_EXTRACT_UTC(SYSTIMESTAMP) - TIMESTAMP '1970-01-01 00:00:00')`;
+/**
+* Epoch milliseconds on the database clock. Oracle evaluates `SYSTIMESTAMP`
+* once per statement, so every reference here reads the same instant, and a
+* statement that waits on a lock compares against the time it started. That
+* error only makes an existing lease look longer and a new lease shorter.
+*/
+const DB_NOW_MS = `(EXTRACT(DAY FROM ${SINCE_EPOCH}) * 86400000 + EXTRACT(HOUR FROM ${SINCE_EPOCH}) * 3600000 + EXTRACT(MINUTE FROM ${SINCE_EPOCH}) * 60000 + FLOOR(EXTRACT(SECOND FROM ${SINCE_EPOCH}) * 1000))`;
+const ORA_UNIQUE_CONSTRAINT = -1;
+const ORA_DEADLOCK = -60;
+const MAX_CLAIM_ATTEMPTS = 5;
+/**
+* The check half of a fenced write; call it first inside the write's
+* transaction. Oracle has no shared row lock, so this takes the claim row
+* `FOR UPDATE`: a claim that updates the row waits for the write to commit,
+* and a write queued behind a claim re-reads the row once the claim commits
+* and sees the new generation. Writes from one run serialize on its row,
+* which they mostly do anyway.
+*/
+async function assertRunFence(client, claimsTable, fence, operation) {
+	const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${claimsTable} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
+	if (!(0, _mastra_core_storage.matchesRunFence)(row ? {
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId)
+	} : null, fence)) throw new _mastra_core_storage.RunFenceConflictError(fence, operation);
+}
+/**
+* Runs `write` in a transaction, behind the fence check when it carries a
+* fence.
+*/
+function withRunFence(db, claimsTable, fence, operation, write) {
+	return db.tx(async (client) => {
+		if (fence) await assertRunFence(client, claimsTable, fence, operation);
+		return write(client);
+	});
+}
+/**
+* Runs a transaction that creates or updates a run's claim row, retrying when
+* two first claims race to insert it. `FOR UPDATE` locks nothing while the row
+* is missing, so racing first claims both insert; the second waits on the
+* primary key and fails once the first commits. On retry the row exists and
+* the claim serializes behind its row lock. A deadlock is retried too.
+*/
+async function claimTransaction(db, fn) {
+	for (let attempt = 1;; attempt++) try {
+		return await db.tx((client) => fn(client));
+	} catch (error) {
+		const retryable = isOracleErrorCode(error, [ORA_UNIQUE_CONSTRAINT, ORA_DEADLOCK]);
+		if (attempt >= MAX_CLAIM_ATTEMPTS || !retryable) throw error;
+	}
+}
+//#endregion
 //#region src/storage/domains/memory/utils.ts
 const STORE_NAME$5 = "ORACLEDB";
 const EMPTY_STRING_SENTINEL = "__MASTRA_ORACLE_EMPTY_STRING__";
@@ -3376,6 +3494,14 @@ const STRING_SENTINEL_ESCAPE_PREFIX = "__MASTRA_ORACLE_ESCAPED__";
 function table(ctx, tableName) {
 	return qualifyName(tableName, ctx.schemaName);
 }
+/**
+* The fence check for a memory write; call it first inside the write's
+* transaction. `fence` is the one `MemoryOracle` already resolved against the
+* run fence scope, so an unfenced write skips the check.
+*/
+async function assertMemoryFence(ctx, client, fence, operation) {
+	if (fence) await assertRunFence(client, table(ctx, _mastra_core_storage.TABLE_MEMORY_RUN_FENCES), fence, operation);
+}
 function storageError$1(operation, reason, details, cause, category = _mastra_core_error.ErrorCategory.THIRD_PARTY) {
 	return createOracleStorageError({
 		storeName: STORE_NAME$5,
@@ -3406,6 +3532,17 @@ function chunkValues(values, size = 900) {
 	for (let index = 0; index < values.length; index += size) chunks.push(values.slice(index, index + size));
 	return chunks;
 }
+/**
+* Bind an instant as TIMESTAMP WITH TIME ZONE. A bare `Date` binds as TIMESTAMP WITH LOCAL
+* TIME ZONE, which the server converts with the session's fixed offset (captured at connect
+* time); an instant on the other side of a DST change is then stored shifted by an hour.
+*/
+function timestampBind(value) {
+	return value === void 0 || value === null ? null : {
+		type: oracledb.default.DB_TYPE_TIMESTAMP_TZ,
+		val: toDate(value)
+	};
+}
 function boolToNumber(value) {
 	return value ? 1 : 0;
 }
@@ -3554,12 +3691,48 @@ const OM_LAST_BUFFERED_AT_TOKENS = "\"lastBufferedAtTokens\"";
 const OM_LAST_BUFFERED_AT_TIME = "\"lastBufferedAtTime\"";
 const OM_CREATED_AT = "\"createdAt\"";
 const OM_UPDATED_AT = "\"updatedAt\"";
+const OM_SUPERSEDED_BY = "\"supersededBy\"";
 async function initMemorySchema(ctx) {
 	await ctx.db.withConnection(async (connection) => {
 		await createTables(ctx, connection);
 		await createIndexes(ctx, connection);
+		await backfillObservationalMemorySupersededBy(ctx, connection);
 	});
 }
+/**
+* Retire every live observational memory row that sorts after its key's canonical head
+* (`generationCount DESC, createdAt ASC, id ASC`), marking it superseded by the head. Rows
+* retired by older adapter versions (which never set `supersededBy`) become frozen. Idempotent.
+* One statement: the head's ordering key is part of the condition, so a row created by a
+* concurrent rollover (higher generation) never matches, and a row locked by one is
+* re-evaluated after it commits.
+*/
+async function backfillObservationalMemorySupersededBy(ctx, connection) {
+	const om = table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY);
+	const heads = `
+    SELECT ${OM_LOOKUP_KEY} AS head_key, id AS head_id, ${OM_GENERATION_COUNT} AS head_gen, ${OM_CREATED_AT} AS head_created
+    FROM (
+      SELECT ${OM_LOOKUP_KEY}, id, ${OM_GENERATION_COUNT}, ${OM_CREATED_AT},
+        ROW_NUMBER() OVER (PARTITION BY ${OM_LOOKUP_KEY} ORDER BY ${OM_GENERATION_COUNT} DESC, ${OM_CREATED_AT} ASC, id ASC) AS rn
+      FROM ${om}
+      WHERE ${OM_LOOKUP_KEY} IN (
+        SELECT ${OM_LOOKUP_KEY} FROM ${om} WHERE ${OM_SUPERSEDED_BY} IS NULL GROUP BY ${OM_LOOKUP_KEY} HAVING COUNT(*) > 1
+      )
+    )
+    WHERE rn = 1`;
+	await connection.execute(`UPDATE ${om} r
+       SET r.${OM_SUPERSEDED_BY} = (SELECT h.head_id FROM (${heads}) h WHERE h.head_key = r.${OM_LOOKUP_KEY})
+     WHERE r.${OM_SUPERSEDED_BY} IS NULL
+       AND EXISTS (
+         SELECT 1 FROM (${heads}) h
+         WHERE h.head_key = r.${OM_LOOKUP_KEY}
+           AND (
+             r.${OM_GENERATION_COUNT} < h.head_gen
+             OR (r.${OM_GENERATION_COUNT} = h.head_gen AND r.${OM_CREATED_AT} > h.head_created)
+             OR (r.${OM_GENERATION_COUNT} = h.head_gen AND r.${OM_CREATED_AT} = h.head_created AND r.id > h.head_id)
+           )
+       )`, {}, { autoCommit: true });
+}
 async function clearAllMemoryTables(ctx) {
 	await ctx.db.tx(async (client) => {
 		await client.none(`DELETE FROM ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}`);
@@ -3633,7 +3806,8 @@ async function createTables(ctx, connection) {
       ${OM_LAST_BUFFERED_AT_TIME} TIMESTAMP WITH TIME ZONE,
       metadata JSON,
       ${OM_CREATED_AT} TIMESTAMP WITH TIME ZONE NOT NULL,
-      ${OM_UPDATED_AT} TIMESTAMP WITH TIME ZONE NOT NULL
+      ${OM_UPDATED_AT} TIMESTAMP WITH TIME ZONE NOT NULL,
+      ${OM_SUPERSEDED_BY} VARCHAR2(512)
     )`, [-955]);
 	await ensureObservationalMemoryColumns(ctx, connection);
 	await relaxObservationalMemoryNullability(ctx, connection);
@@ -3771,6 +3945,10 @@ async function ensureObservationalMemoryColumns(ctx, connection) {
 		{
 			name: OM_UPDATED_AT,
 			type: "TIMESTAMP WITH TIME ZONE"
+		},
+		{
+			name: OM_SUPERSEDED_BY,
+			type: "VARCHAR2(512)"
 		}
 	];
 	for (const column of columns) await executeDdl(connection, `ALTER TABLE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)} ADD (${column.name} ${column.type})`, [-1430]);
@@ -3881,7 +4059,7 @@ async function listMessagesByResourceId(ctx, args) {
 		orderBy
 	});
 }
-async function saveMessages(ctx, { messages }) {
+async function saveMessages(ctx, { messages, fence }) {
 	if (messages.length === 0) return { messages: [] };
 	const threadIds = /* @__PURE__ */ new Set();
 	try {
@@ -3891,6 +4069,7 @@ async function saveMessages(ctx, { messages }) {
 		}
 		for (const threadId of threadIds) if (!await ctx.getThreadById({ threadId })) throw storageError$1("SAVE_MESSAGES", "FAILED", { threadId }, /* @__PURE__ */ new Error(`Thread ${threadId} not found`), _mastra_core_error.ErrorCategory.USER);
 		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "saveMessages");
 			await insertMessageBatch(ctx, client, messages);
 		});
 		return { messages: new _mastra_core_agent.MessageList().add(messages, "memory").get.all.db() };
@@ -3968,7 +4147,7 @@ async function insertMessageBatch(ctx, client, messages) {
 		threadId: messageThreadId
 	})));
 }
-async function updateMessages(ctx, { messages }) {
+async function updateMessages(ctx, { messages, fence }) {
 	if (messages.length === 0) return [];
 	const messageIds = messages.map((message) => message.id);
 	const existingMessages = (await ctx.listMessagesById({ messageIds })).messages;
@@ -3977,6 +4156,7 @@ async function updateMessages(ctx, { messages }) {
 	const threadIdsToUpdate = /* @__PURE__ */ new Set();
 	try {
 		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "updateMessages");
 			const semanticRecallMessageIds = [];
 			for (const updatePayload of messages) {
 				const existing = existingById.get(updatePayload.id);
@@ -4023,13 +4203,15 @@ async function updateMessages(ctx, { messages }) {
 		});
 		return (await ctx.listMessagesById({ messageIds })).messages;
 	} catch (error) {
+		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw storageError$1("UPDATE_MESSAGES", "FAILED", { messageIds: messageIds.join(",") }, error);
 	}
 }
-async function deleteMessages(ctx, messageIds) {
+async function deleteMessages(ctx, messageIds, fence) {
 	if (!messageIds.length) return;
 	try {
 		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "deleteMessages");
 			const threadIds = /* @__PURE__ */ new Set();
 			for (const [chunkIndex, chunk] of chunkValues(messageIds).entries()) {
 				const { sql, binds } = inClause(`messageId${chunkIndex}`, chunk);
@@ -4045,6 +4227,7 @@ async function deleteMessages(ctx, messageIds) {
 			})));
 		});
 	} catch (error) {
+		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw storageError$1("DELETE_MESSAGES", "FAILED", { messageIds: messageIds.join(",") }, error);
 	}
 }
@@ -4286,14 +4469,15 @@ function mergeMessageContent(existingContent, updateContent) {
 }
 //#endregion
 //#region src/storage/domains/memory/observational.ts
+/** Hops a write aimed at a retired record may follow to reach the head before giving up. */
+const OM_MAX_HEAD_HOPS = 3;
+/** Canonical head order for a lookup key. */
+const OM_HEAD_ORDER = `${OM_GENERATION_COUNT} DESC, ${OM_CREATED_AT} ASC, id ASC`;
 async function getObservationalMemory(ctx, threadId, resourceId) {
 	try {
 		const lookupKey = getOMKey(threadId, resourceId);
 		return await ctx.db.withConnection(async (connection) => {
-			const row = rows(await connection.execute(`${omSelect()} FROM ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
-         WHERE ${OM_LOOKUP_KEY} = :lookupKey
-         ORDER BY ${OM_GENERATION_COUNT} DESC
-         FETCH FIRST 1 ROWS ONLY`, asBindParameters({ lookupKey }), executeOptions()))[0];
+			const row = await getHeadOMRow(ctx, connection, lookupKey);
 			return row ? parseOMRow(row) : null;
 		});
 	} catch (error) {
@@ -4325,11 +4509,11 @@ async function getObservationalMemoryHistory(ctx, threadId, resourceId, limit =
 		}
 		if (options?.from) {
 			conditions.push(`${OM_CREATED_AT} >= :fromDate`);
-			binds.fromDate = options.from;
+			binds.fromDate = timestampBind(options.from);
 		}
 		if (options?.to) {
 			conditions.push(`${OM_CREATED_AT} <= :toDate`);
-			binds.toDate = options.to;
+			binds.toDate = timestampBind(options.to);
 		}
 		if (options?.groupId !== void 0) {
 			conditions.push(`(DBMS_LOB.INSTR(${OM_ACTIVE_OBSERVATIONS}, :groupPrefix) > 0 OR EXISTS (
@@ -4368,6 +4552,7 @@ async function getObservationalMemoryHistory(ctx, threadId, resourceId, limit =
 }
 async function initializeObservationalMemory(ctx, input) {
 	const now = /* @__PURE__ */ new Date();
+	const lookupKey = getOMKey(input.threadId, input.resourceId);
 	const record = {
 		id: globalThis.crypto.randomUUID(),
 		scope: input.scope,
@@ -4389,13 +4574,22 @@ async function initializeObservationalMemory(ctx, input) {
 		lastBufferedAtTokens: 0,
 		lastBufferedAtTime: null,
 		config: input.config,
-		observedTimezone: input.observedTimezone
+		observedTimezone: input.observedTimezone,
+		supersededBy: null
 	};
 	try {
-		await ctx.db.tx(async (_client, connection) => {
+		const existing = await getObservationalMemory(ctx, input.threadId, input.resourceId);
+		if (existing) return existing;
+		if (await ctx.db.tx(async (_client, connection) => {
+			const omTable = table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY);
+			await connection.execute(`LOCK TABLE ${omTable} IN SHARE ROW EXCLUSIVE MODE`);
+			if ((await connection.execute(`SELECT 1 FROM ${omTable} WHERE "lookupKey" = :lookupKey AND "supersededBy" IS NULL FETCH FIRST 1 ROWS ONLY`, { lookupKey })).rows?.length) return false;
 			await insertOMRecord(ctx, connection, record);
-		});
-		return record;
+			return true;
+		})) return record;
+		const head = await getObservationalMemory(ctx, input.threadId, input.resourceId);
+		if (!head) throw new Error(`Observational memory record not found after initialization: ${lookupKey}`);
+		return head;
 	} catch (error) {
 		throw storageError$1("INITIALIZE_OBSERVATIONAL_MEMORY", "FAILED", {
 			threadId: input.threadId ?? "",
@@ -4415,9 +4609,20 @@ async function insertObservationalMemoryRecord(ctx, record) {
 		}, error);
 	}
 }
-async function updateActiveObservations(ctx, input) {
+async function updateActiveObservations(ctx, input, fence) {
 	try {
-		await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "commitActiveObservations");
+			const row = await lockOMRow(ctx, connection, input.id, "UPDATE_ACTIVE_OBSERVATIONS");
+			if (row.supersededBy) return {
+				applied: false,
+				reason: "retired"
+			};
+			if (input.expectedActiveObservations !== void 0 && input.expectedActiveObservations !== stringOrEmpty(row.activeObservations)) return {
+				applied: false,
+				reason: "conflict"
+			};
+			const lastObservedAt = maxObservationCursor(row.lastObservedAt, input.lastObservedAt);
 			assertRowsAffected((await connection.execute(`
           UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
           SET ${OM_ACTIVE_OBSERVATIONS} = :activeObservations,
@@ -4431,52 +4636,88 @@ async function updateActiveObservations(ctx, input) {
           WHERE id = :id`, {
 				id: input.id,
 				activeObservations: nullableClobBind(input.observations),
-				lastObservedAt: input.lastObservedAt,
+				lastObservedAt: timestampBind(lastObservedAt),
 				tokenCount: Math.round(input.tokenCount),
 				observedMessageIds: nullableJsonBind(input.observedMessageIds),
 				observedTimezone: input.observedTimezone ?? null,
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: timestampBind(/* @__PURE__ */ new Date())
 			})).rowsAffected, "UPDATE_ACTIVE_OBSERVATIONS", input.id);
+			return { applied: true };
 		});
 	} catch (error) {
 		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw storageError$1("UPDATE_ACTIVE_OBSERVATIONS", "FAILED", { id: input.id }, error);
 	}
 }
-async function createReflectionGeneration(ctx, input) {
+async function createReflectionGeneration(ctx, input, fence) {
+	const { currentRecord } = input;
+	try {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "createReflectionGeneration");
+			const row = await findOMRowForUpdate(ctx, connection, currentRecord.id);
+			if (!row) return currentRecord;
+			if (row.supersededBy) return parseOMRow(await resolveLiveOMRow(ctx, connection, row));
+			const stored = parseOMRow(row);
+			const plan = planReflectionGenerationText({
+				storedObservations: stored.activeObservations,
+				storedObservationTokenCount: stored.observationTokenCount,
+				snapshotObservations: currentRecord.activeObservations,
+				snapshotObservationTokenCount: currentRecord.observationTokenCount,
+				reflection: input.reflection,
+				tokenCount: input.tokenCount
+			});
+			if (!plan) return stored;
+			return rollOverOMRow(ctx, connection, stored, plan.observations, plan.tokenCount, input.newRecordId);
+		});
+	} catch (error) {
+		if (error instanceof _mastra_core_error.MastraError) throw error;
+		throw storageError$1("CREATE_REFLECTION_GENERATION", "FAILED", { id: currentRecord.id }, error);
+	}
+}
+/**
+* Create the next generation from the stored (live, row-locked) record and retire it in the
+* same transaction. Buffered chunks move to the new generation; the cursor, buffering markers,
+* flags, and counters carry over; buffered reflection state does not.
+*/
+async function rollOverOMRow(ctx, connection, stored, observations, tokenCount, newRecordId) {
 	const now = /* @__PURE__ */ new Date();
 	const record = {
-		id: globalThis.crypto.randomUUID(),
-		scope: input.currentRecord.scope,
-		threadId: input.currentRecord.threadId,
-		resourceId: input.currentRecord.resourceId,
+		id: newRecordId ?? globalThis.crypto.randomUUID(),
+		scope: stored.scope,
+		threadId: stored.threadId,
+		resourceId: stored.resourceId,
 		createdAt: now,
 		updatedAt: now,
-		lastObservedAt: input.currentRecord.lastObservedAt,
+		lastObservedAt: stored.lastObservedAt,
 		originType: "reflection",
-		generationCount: input.currentRecord.generationCount + 1,
-		activeObservations: input.reflection,
-		totalTokensObserved: input.currentRecord.totalTokensObserved,
-		observationTokenCount: Math.round(input.tokenCount),
-		pendingMessageTokens: 0,
+		generationCount: stored.generationCount + 1,
+		activeObservations: observations,
+		totalTokensObserved: stored.totalTokensObserved,
+		observationTokenCount: Math.round(tokenCount),
+		pendingMessageTokens: stored.pendingMessageTokens,
 		isReflecting: false,
 		isObserving: false,
-		isBufferingObservation: false,
+		isBufferingObservation: stored.isBufferingObservation,
 		isBufferingReflection: false,
-		lastBufferedAtTokens: 0,
-		lastBufferedAtTime: null,
-		config: input.currentRecord.config,
-		metadata: input.currentRecord.metadata,
-		observedTimezone: input.currentRecord.observedTimezone
+		lastBufferedAtTokens: stored.lastBufferedAtTokens,
+		lastBufferedAtTime: stored.lastBufferedAtTime ?? null,
+		bufferedObservationChunks: stored.bufferedObservationChunks?.length ? stored.bufferedObservationChunks : void 0,
+		config: stored.config,
+		metadata: stored.metadata,
+		observedTimezone: stored.observedTimezone,
+		supersededBy: null
 	};
-	try {
-		await ctx.db.tx(async (_client, connection) => {
-			await insertOMRecord(ctx, connection, record, now);
-		});
-		return record;
-	} catch (error) {
-		throw storageError$1("CREATE_REFLECTION_GENERATION", "FAILED", { id: input.currentRecord.id }, error);
-	}
+	await insertOMRecord(ctx, connection, record, now);
+	if ((await connection.execute(`UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
+       SET "supersededBy" = :newId,
+           "bufferedObservationChunks" = NULL,
+           "updatedAt" = :updatedAt
+     WHERE id = :id AND "supersededBy" IS NULL`, {
+		newId: record.id,
+		updatedAt: timestampBind(now),
+		id: stored.id
+	})).rowsAffected !== 1) throw storageError$1("CREATE_REFLECTION_GENERATION", "RETIRE_FAILED", { id: stored.id }, /* @__PURE__ */ new Error(`Failed to retire observational memory record ${stored.id}`));
+	return record;
 }
 async function setReflectingFlag(ctx, id, isReflecting) {
 	await updateOMFlag(ctx, id, OM_IS_REFLECTING, isReflecting, "SET_REFLECTING_FLAG");
@@ -4491,9 +4732,10 @@ async function setBufferingObservationFlag(ctx, id, isBuffering, lastBufferedAtT
 			const binds = {
 				id,
 				isBuffering: boolToNumber(isBuffering),
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: timestampBind(/* @__PURE__ */ new Date())
 			};
 			if (lastBufferedAtTokens !== void 0) binds.lastBufferedAtTokens = Math.round(lastBufferedAtTokens);
+			binds.id = (await resolveLiveOMRow(ctx, connection, await lockOMRow(ctx, connection, id, "SET_BUFFERING_OBSERVATION_FLAG"))).id;
 			assertRowsAffected((await connection.execute(`UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
            SET ${OM_IS_BUFFERING_OBSERVATION} = :isBuffering,
                ${OM_UPDATED_AT} = :updatedAt
@@ -4524,7 +4766,17 @@ async function clearObservationalMemory(ctx, threadId, resourceId) {
 }
 async function setPendingMessageTokens(ctx, id, tokenCount) {
 	try {
-		await updateOMColumns(ctx, id, "SET_PENDING_MESSAGE_TOKENS", { [OM_PENDING_MESSAGE_TOKENS]: Math.round(tokenCount) });
+		await ctx.db.tx(async (_client, connection) => {
+			const target = await resolveLiveOMRow(ctx, connection, await lockOMRow(ctx, connection, id, "SET_PENDING_MESSAGE_TOKENS"));
+			assertRowsAffected((await connection.execute(`UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
+           SET ${OM_PENDING_MESSAGE_TOKENS} = :tokenCount,
+               ${OM_UPDATED_AT} = :updatedAt
+           WHERE id = :id`, {
+				tokenCount: Math.round(tokenCount),
+				updatedAt: timestampBind(/* @__PURE__ */ new Date()),
+				id: target.id
+			})).rowsAffected, "SET_PENDING_MESSAGE_TOKENS", id);
+		});
 	} catch (error) {
 		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw storageError$1("SET_PENDING_MESSAGE_TOKENS", "FAILED", {
@@ -4546,7 +4798,7 @@ async function updateObservationalMemoryConfig(ctx, input) {
            WHERE id = :id`, {
 				id: input.id,
 				config: jsonBind(merged),
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: timestampBind(/* @__PURE__ */ new Date())
 			})).rowsAffected, "UPDATE_OM_CONFIG", input.id);
 		});
 	} catch (error) {
@@ -4592,6 +4844,7 @@ async function insertOMRecord(ctx, connection, record, timestamp = record.create
       ${OM_LAST_BUFFERED_AT_TOKENS},
       ${OM_LAST_BUFFERED_AT_TIME},
       metadata,
+      ${OM_SUPERSEDED_BY},
       ${OM_CREATED_AT},
       ${OM_UPDATED_AT}
     ) VALUES (
@@ -4627,6 +4880,7 @@ async function insertOMRecord(ctx, connection, record, timestamp = record.create
       :lastBufferedAtTokens,
       :lastBufferedAtTime,
       :metadata,
+      :supersededBy,
       :createdAt,
       :updatedAt
     )`, {
@@ -4640,8 +4894,8 @@ async function insertOMRecord(ctx, connection, record, timestamp = record.create
 		originType: record.originType ?? "initial",
 		config: jsonBind(record.config ?? {}),
 		generationCount: record.generationCount ?? 0,
-		lastObservedAt: record.lastObservedAt ?? null,
-		lastReflectionAt: record.originType === "reflection" ? timestamp : null,
+		lastObservedAt: timestampBind(record.lastObservedAt),
+		lastReflectionAt: record.originType === "reflection" ? timestampBind(timestamp) : null,
 		pendingMessageTokens: Math.round(record.pendingMessageTokens ?? 0),
 		totalTokensObserved: Math.round(record.totalTokensObserved ?? 0),
 		observationTokenCount: Math.round(record.observationTokenCount ?? 0),
@@ -4660,10 +4914,11 @@ async function insertOMRecord(ctx, connection, record, timestamp = record.create
 		isBufferingObservation: boolToNumber(record.isBufferingObservation),
 		isBufferingReflection: boolToNumber(record.isBufferingReflection),
 		lastBufferedAtTokens: Math.round(record.lastBufferedAtTokens ?? 0),
-		lastBufferedAtTime: record.lastBufferedAtTime ?? null,
+		lastBufferedAtTime: timestampBind(record.lastBufferedAtTime),
 		metadata: nullableJsonBind(record.metadata),
-		createdAt: record.createdAt,
-		updatedAt: record.updatedAt
+		supersededBy: record.supersededBy ?? null,
+		createdAt: timestampBind(record.createdAt),
+		updatedAt: timestampBind(record.updatedAt)
 	});
 }
 async function updateOMFlag(ctx, id, column, value, operation) {
@@ -4687,7 +4942,7 @@ async function updateOMColumns(ctx, id, operation, columns) {
          WHERE id = :id`, {
 			...binds,
 			id,
-			updatedAt: /* @__PURE__ */ new Date()
+			updatedAt: timestampBind(/* @__PURE__ */ new Date())
 		})).rowsAffected, operation, id);
 	});
 }
@@ -4725,6 +4980,7 @@ function omSelect() {
     ${OM_LAST_BUFFERED_AT_TOKENS} AS "lastBufferedAtTokens",
     ${OM_LAST_BUFFERED_AT_TIME} AS "lastBufferedAtTime",
     metadata AS "metadata",
+    ${OM_SUPERSEDED_BY} AS "supersededBy",
     ${OM_CREATED_AT} AS "createdAt",
     ${OM_UPDATED_AT} AS "updatedAt"`;
 }
@@ -4760,15 +5016,61 @@ function parseOMRow(row) {
 		config: parseJson(row.config),
 		metadata: parseOptionalJsonObject(row.metadata, { emptyObjectAsUndefined: true }),
 		observedMessageIds: parseOptionalStringArray(row.observedMessageIds),
-		observedTimezone: row.observedTimezone ? String(row.observedTimezone) : void 0
+		observedTimezone: row.observedTimezone ? String(row.observedTimezone) : void 0,
+		supersededBy: row.supersededBy ? String(row.supersededBy) : null
 	};
 }
+/** The canonical head row of a lookup key (non-locking read). */
+async function getHeadOMRow(ctx, connection, lookupKey) {
+	return rows(await connection.execute(`${omSelect()} FROM ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
+     WHERE ${OM_LOOKUP_KEY} = :lookupKey
+     ORDER BY ${OM_HEAD_ORDER}
+     FETCH FIRST 1 ROWS ONLY`, asBindParameters({ lookupKey }), executeOptions()))[0];
+}
+/** Row-locks one record by primary key for the rest of the transaction; `undefined` when missing. */
+async function findOMRowForUpdate(ctx, connection, id) {
+	return rows(await connection.execute(`${omSelect()} FROM ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)} WHERE id = :id FOR UPDATE`, { id }, executeOptions()))[0];
+}
+/**
+* Row-locks one record by primary key. Observational memory updates are incremental and
+* order-sensitive, so mutating paths derive their next state from a locked row.
+* Throws "record not found" when it is missing.
+*/
+async function lockOMRow(ctx, connection, id, operation) {
+	const row = await findOMRowForUpdate(ctx, connection, id);
+	if (!row) {
+		assertRowsAffected(0, operation, id);
+		throw new Error(`Observational memory record not found: ${id}`);
+	}
+	return row;
+}
+/**
+* The live, row-locked record a lifecycle write aimed at `row` lands on: `row` itself while
+* live, otherwise the head of its lookup key (locked, then re-checked — a rollover may retire
+* it between the head read and the lock).
+*/
+async function resolveLiveOMRow(ctx, connection, row) {
+	let current = row;
+	for (let hop = 0; current.supersededBy; hop++) {
+		const head = hop < OM_MAX_HEAD_HOPS ? await getHeadOMRow(ctx, connection, current.lookupKey) : void 0;
+		const locked = head && head.id !== current.id ? await findOMRowForUpdate(ctx, connection, head.id) : void 0;
+		if (!locked) throw storageError$1("RESOLVE_OBSERVATIONAL_MEMORY_HEAD", "FAILED", { id: row.id }, /* @__PURE__ */ new Error(`Observational memory record ${row.id} is superseded but no live head was found`));
+		current = locked;
+	}
+	return current;
+}
 //#endregion
 //#region src/storage/domains/memory/observational-buffering.ts
-async function updateBufferedObservations(ctx, input) {
+async function updateBufferedObservations(ctx, input, fence) {
 	try {
-		await ctx.db.tx(async (_client, connection) => {
-			const existingChunks = parseBufferedChunks((await lockOMRow(ctx, connection, input.id, "UPDATE_BUFFERED_OBSERVATIONS")).bufferedObservationChunks);
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "appendBufferedObservations");
+			const row = await resolveLiveOMRow(ctx, connection, await lockOMRow(ctx, connection, input.id, "UPDATE_BUFFERED_OBSERVATIONS"));
+			const existingChunks = parseBufferedChunks(row.bufferedObservationChunks);
+			if (existingChunks.some((existing) => existing.cycleId === input.chunk.cycleId) || isBufferedChunkCoveredByCursor(input.chunk.lastObservedAt, row.lastObservedAt)) return {
+				persisted: false,
+				recordId: row.id
+			};
 			const newChunk = {
 				id: `ombuf-${globalThis.crypto.randomUUID()}`,
 				cycleId: input.chunk.cycleId,
@@ -4784,32 +5086,48 @@ async function updateBufferedObservations(ctx, input) {
 				extractedValues: input.chunk.extractedValues,
 				extractionFailures: input.chunk.extractionFailures
 			};
-			const updatedChunks = [...existingChunks, newChunk];
-			const lastBufferedAtTimeSql = input.lastBufferedAtTime === void 0 || input.lastBufferedAtTime === null ? "" : `,\n               ${OM_LAST_BUFFERED_AT_TIME} = :lastBufferedAtTime`;
-			const binds = {
-				id: input.id,
-				bufferedObservationChunks: nullableJsonBind(updatedChunks),
-				updatedAt: /* @__PURE__ */ new Date()
-			};
-			if (input.lastBufferedAtTime !== void 0 && input.lastBufferedAtTime !== null) binds.lastBufferedAtTime = toDate(input.lastBufferedAtTime);
+			const lastBufferedAtTime = maxObservationCursor(row.lastBufferedAtTime, input.lastBufferedAtTime);
 			assertRowsAffected((await connection.execute(`UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
            SET ${OM_BUFFERED_OBSERVATION_CHUNKS} = :bufferedObservationChunks,
-               ${OM_UPDATED_AT} = :updatedAt${lastBufferedAtTimeSql}
-           WHERE id = :id`, asBindParameters(binds))).rowsAffected, "UPDATE_BUFFERED_OBSERVATIONS", input.id);
+               ${OM_LAST_BUFFERED_AT_TIME} = :lastBufferedAtTime,
+               ${OM_UPDATED_AT} = :updatedAt
+           WHERE id = :id`, asBindParameters({
+				id: row.id,
+				bufferedObservationChunks: nullableJsonBind([...existingChunks, newChunk]),
+				lastBufferedAtTime: timestampBind(lastBufferedAtTime),
+				updatedAt: timestampBind(/* @__PURE__ */ new Date())
+			}))).rowsAffected, "UPDATE_BUFFERED_OBSERVATIONS", row.id);
+			return {
+				persisted: true,
+				recordId: row.id
+			};
 		});
 	} catch (error) {
 		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw storageError$1("UPDATE_BUFFERED_OBSERVATIONS", "FAILED", { id: input.id }, error);
 	}
 }
-async function swapBufferedToActive(ctx, input) {
+async function swapBufferedToActive(ctx, input, fence) {
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "swapBufferedToActive");
 			const row = await lockOMRow(ctx, connection, input.id, "SWAP_BUFFERED_TO_ACTIVE");
-			const chunks = input.bufferedChunks?.length ? input.bufferedChunks : parseBufferedChunks(row.bufferedObservationChunks);
+			if (row.supersededBy) return {
+				...emptySwapResult(),
+				retired: true
+			};
+			const refreshedWeights = new Map((input.bufferedChunks ?? []).map((chunk) => [chunk.id, chunk.messageTokens]));
+			const chunks = parseBufferedChunks(row.bufferedObservationChunks).map((chunk) => {
+				const weight = refreshedWeights.get(chunk.id);
+				return weight === void 0 ? chunk : {
+					...chunk,
+					messageTokens: weight
+				};
+			});
 			if (chunks.length === 0) return emptySwapResult();
 			const activation = calculateBufferedActivation(chunks, input);
 			const lastObservedAt = input.lastObservedAt ?? (activation.activatedChunks.at(-1)?.lastObservedAt ? toDate(activation.activatedChunks.at(-1).lastObservedAt) : /* @__PURE__ */ new Date());
+			const storedCursor = maxObservationCursor(row.lastObservedAt, lastObservedAt);
 			const boundary = `\n\n--- message boundary (${lastObservedAt.toISOString()}) ---\n\n`;
 			const existingActive = stringOrEmpty(row.activeObservations);
 			const newActive = existingActive ? `${existingActive}${boundary}${activation.activatedContent}` : activation.activatedContent;
@@ -4827,8 +5145,8 @@ async function swapBufferedToActive(ctx, input) {
 				observationTokens: activation.activatedTokens,
 				pendingMessageTokens: pendingTokens,
 				bufferedObservationChunks: nullableJsonBind(activation.remainingChunks.length > 0 ? activation.remainingChunks : null),
-				lastObservedAt,
-				updatedAt: /* @__PURE__ */ new Date()
+				lastObservedAt: timestampBind(storedCursor),
+				updatedAt: timestampBind(/* @__PURE__ */ new Date())
 			})).rowsAffected, "SWAP_BUFFERED_TO_ACTIVE", input.id);
 			return activation.result;
 		});
@@ -4837,9 +5155,10 @@ async function swapBufferedToActive(ctx, input) {
 		throw storageError$1("SWAP_BUFFERED_TO_ACTIVE", "FAILED", { id: input.id }, error);
 	}
 }
-async function updateBufferedReflection(ctx, input) {
+async function updateBufferedReflection(ctx, input, fence) {
 	try {
-		await ctx.db.tx(async (_client, connection) => {
+		await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "updateBufferedReflection");
 			assertRowsAffected((await connection.execute(`UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
            SET ${OM_BUFFERED_REFLECTION} = CASE
                  WHEN ${OM_BUFFERED_REFLECTION} IS NOT NULL AND DBMS_LOB.GETLENGTH(${OM_BUFFERED_REFLECTION}) > 0
@@ -4856,7 +5175,7 @@ async function updateBufferedReflection(ctx, input) {
 				tokenCount: Math.round(input.tokenCount),
 				inputTokenCount: Math.round(input.inputTokenCount),
 				reflectedObservationLineCount: Math.round(input.reflectedObservationLineCount),
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: timestampBind(/* @__PURE__ */ new Date())
 			})).rowsAffected, "UPDATE_BUFFERED_REFLECTION", input.id);
 		});
 	} catch (error) {
@@ -4864,67 +5183,34 @@ async function updateBufferedReflection(ctx, input) {
 		throw storageError$1("UPDATE_BUFFERED_REFLECTION", "FAILED", { id: input.id }, error);
 	}
 }
-async function swapBufferedReflectionToActive(ctx, input) {
+async function swapBufferedReflectionToActive(ctx, input, fence) {
+	const { currentRecord } = input;
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
-			const row = await lockOMRow(ctx, connection, input.currentRecord.id, "SWAP_BUFFERED_REFLECTION_TO_ACTIVE");
-			const bufferedReflection = stringOrEmpty(row.bufferedReflection);
-			if (!bufferedReflection) throw storageError$1("SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NO_CONTENT", { id: input.currentRecord.id }, /* @__PURE__ */ new Error("No buffered reflection to swap"), _mastra_core_error.ErrorCategory.USER);
-			const reflectedLineCount = numberOrZero(row.reflectedObservationLineCount);
-			const unreflectedContent = stringOrEmpty(row.activeObservations).split("\n").slice(reflectedLineCount).join("\n").trim();
-			const newObservations = unreflectedContent ? `${bufferedReflection}\n\n${unreflectedContent}` : bufferedReflection;
-			const now = /* @__PURE__ */ new Date();
-			const lockedRecord = parseOMRow(row);
-			const newRecord = {
-				id: globalThis.crypto.randomUUID(),
-				scope: lockedRecord.scope,
-				threadId: lockedRecord.threadId,
-				resourceId: lockedRecord.resourceId,
-				createdAt: now,
-				updatedAt: now,
-				lastObservedAt: lockedRecord.lastObservedAt,
-				originType: "reflection",
-				generationCount: lockedRecord.generationCount + 1,
-				activeObservations: newObservations,
-				totalTokensObserved: lockedRecord.totalTokensObserved,
-				observationTokenCount: Math.round(input.tokenCount),
-				pendingMessageTokens: 0,
-				isReflecting: false,
-				isObserving: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				config: lockedRecord.config,
-				metadata: lockedRecord.metadata,
-				observedTimezone: lockedRecord.observedTimezone
-			};
-			await insertOMRecord(ctx, connection, newRecord, now);
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "swapBufferedReflectionToActive");
+			const row = await findOMRowForUpdate(ctx, connection, currentRecord.id);
+			if (!row) return currentRecord;
+			if (row.supersededBy) return parseOMRow(await resolveLiveOMRow(ctx, connection, row));
+			const stored = parseOMRow(row);
+			const bufferedReflection = stored.bufferedReflection ?? "";
+			if (!bufferedReflection) throw storageError$1("SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "NO_CONTENT", { id: currentRecord.id }, /* @__PURE__ */ new Error("No buffered reflection to swap"), _mastra_core_error.ErrorCategory.USER);
+			if (!isAppendOnlySince(stored.activeObservations, currentRecord.activeObservations)) return stored;
+			const reflectedLineCount = stored.reflectedObservationLineCount ?? 0;
+			const unreflectedContent = stored.activeObservations.split("\n").slice(reflectedLineCount).join("\n").trim();
+			const newRecord = await rollOverOMRow(ctx, connection, stored, unreflectedContent ? `${bufferedReflection}\n\n${unreflectedContent}` : bufferedReflection, input.tokenCount + Math.max(0, stored.observationTokenCount - (currentRecord.observationTokenCount ?? 0)), input.newRecordId);
 			assertRowsAffected((await connection.execute(`UPDATE ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)}
            SET ${OM_BUFFERED_REFLECTION} = NULL,
                ${OM_BUFFERED_REFLECTION_TOKENS} = NULL,
                ${OM_BUFFERED_REFLECTION_INPUT_TOKENS} = NULL,
-               ${OM_REFLECTED_OBSERVATION_LINE_COUNT} = NULL,
-               ${OM_UPDATED_AT} = :updatedAt
-           WHERE id = :id`, {
-				id: input.currentRecord.id,
-				updatedAt: now
-			})).rowsAffected, "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", input.currentRecord.id);
+               ${OM_REFLECTED_OBSERVATION_LINE_COUNT} = NULL
+           WHERE id = :id`, { id: stored.id })).rowsAffected, "SWAP_BUFFERED_REFLECTION_TO_ACTIVE", stored.id);
 			return newRecord;
 		});
 	} catch (error) {
 		if (error instanceof _mastra_core_error.MastraError) throw error;
-		throw storageError$1("SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "FAILED", { id: input.currentRecord.id }, error);
+		throw storageError$1("SWAP_BUFFERED_REFLECTION_TO_ACTIVE", "FAILED", { id: currentRecord.id }, error);
 	}
 }
-async function lockOMRow(ctx, connection, id, operation) {
-	const row = rows(await connection.execute(`${omSelect()} FROM ${table(ctx, _mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY)} WHERE id = :id FOR UPDATE`, { id }, executeOptions()))[0];
-	if (!row) {
-		assertRowsAffected(0, operation, id);
-		throw new Error(`Observational memory record not found: ${id}`);
-	}
-	return row;
-}
 function emptySwapResult() {
 	return {
 		chunksActivated: 0,
@@ -5054,17 +5340,24 @@ async function saveResource(ctx, { resource }) {
 		throw storageError$1("SAVE_RESOURCE", "FAILED", { resourceId: resource.id }, error);
 	}
 }
-async function updateResource(ctx, { resourceId, workingMemory, metadata }) {
+async function updateResource(ctx, { resourceId, workingMemory, metadata, fence }) {
 	const existing = await ctx.getResourceById({ resourceId });
-	if (!existing) return ctx.saveResource({ resource: {
+	const newResource = () => ({
 		id: resourceId,
 		workingMemory,
 		metadata: metadata ?? {},
 		createdAt: /* @__PURE__ */ new Date(),
 		updatedAt: /* @__PURE__ */ new Date()
-	} });
+	});
+	if (!existing && !fence) return ctx.saveResource({ resource: newResource() });
 	try {
-		return await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (client, connection) => {
+			await assertMemoryFence(ctx, client, fence, "updateResource");
+			if (!existing) {
+				const resource = newResource();
+				await mergeResourceRow(ctx, connection, resource);
+				return resource;
+			}
 			const row = rows(await connection.execute(`${resourceSelect()} FROM ${table(ctx, _mastra_core_storage.TABLE_RESOURCES)} WHERE id = :resourceId FOR UPDATE`, { resourceId }, executeOptions()))[0];
 			const locked = row ? parseResource(row) : existing;
 			const updated = {
@@ -5158,11 +5451,15 @@ async function getThreadById(ctx, { threadId, resourceId }) {
 		throw storageError$1("GET_THREAD_BY_ID", "FAILED", { threadId }, error);
 	}
 }
-async function saveThread(ctx, { thread }) {
+async function saveThread(ctx, { thread, fence }) {
 	try {
-		await mergeThreadRow(ctx, ctx.db, thread);
+		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "saveThread");
+			await mergeThreadRow(ctx, client, thread);
+		});
 		return thread;
 	} catch (error) {
+		if (error instanceof _mastra_core_error.MastraError) throw error;
 		throw storageError$1("SAVE_THREAD", "FAILED", { threadId: thread.id }, error);
 	}
 }
@@ -5247,7 +5544,7 @@ async function insertThreadRow(ctx, client, thread) {
 		updatedAt: thread.updatedAt ?? /* @__PURE__ */ new Date()
 	});
 }
-async function updateThread(ctx, { id, title, metadata }) {
+async function updateThread(ctx, { id, title, metadata, fence }) {
 	const existingThread = await ctx.getThreadById({ threadId: id });
 	if (!existingThread) throw storageError$1("UPDATE_THREAD", "FAILED", {
 		threadId: id,
@@ -5259,16 +5556,19 @@ async function updateThread(ctx, { id, title, metadata }) {
 	};
 	const updatedAt = /* @__PURE__ */ new Date();
 	try {
-		await ctx.db.none(`
-          UPDATE ${table(ctx, _mastra_core_storage.TABLE_THREADS)}
-          SET title = COALESCE(:title, title),
-              metadata = :metadata,
-              ${THREAD_UPDATED_AT} = :updatedAt
-          WHERE id = :id`, {
-			id,
-			title: optionalStringBind(title),
-			metadata: jsonBind(mergedMetadata),
-			updatedAt
+		await ctx.db.tx(async (client) => {
+			await assertMemoryFence(ctx, client, fence, "updateThread");
+			await client.none(`
+            UPDATE ${table(ctx, _mastra_core_storage.TABLE_THREADS)}
+            SET title = COALESCE(:title, title),
+                metadata = :metadata,
+                ${THREAD_UPDATED_AT} = :updatedAt
+            WHERE id = :id`, {
+				id,
+				title: optionalStringBind(title),
+				metadata: jsonBind(mergedMetadata),
+				updatedAt
+			});
 		});
 		const updatedThread = await ctx.getThreadById({ threadId: id });
 		if (!updatedThread) throw storageError$1("UPDATE_THREAD", "FAILED", {
@@ -5420,7 +5720,8 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 		_mastra_core_storage.TABLE_THREADS,
 		_mastra_core_storage.TABLE_MESSAGES,
 		_mastra_core_storage.TABLE_RESOURCES,
-		_mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY
+		_mastra_core_storage.TABLE_OBSERVATIONAL_MEMORY,
+		_mastra_core_storage.TABLE_MEMORY_RUN_FENCES
 	];
 	db;
 	schemaName;
@@ -5458,18 +5759,77 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 	}
 	async init() {
 		await initMemorySchema(this.ctx);
+		await this.db.createTable({
+			tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_MEMORY_RUN_FENCES]
+		});
+	}
+	/**
+	* Mark observational memory rows that are not their key's canonical head as superseded.
+	* Runs as part of `init()`; `OracleStore` also runs it on every start when the memory schema
+	* migration is unchanged and skipped.
+	* @internal
+	*/
+	async backfillObservationalMemorySupersededBy() {
+		await this.ctx.db.withConnection((connection) => backfillObservationalMemorySupersededBy(this.ctx, connection));
 	}
 	async dangerouslyClearAll() {
 		await clearAllMemoryTables(this.ctx);
+		await this.db.clearTable(_mastra_core_storage.TABLE_MEMORY_RUN_FENCES);
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async raiseRunFence(fence) {
+		const fences = table(this.ctx, _mastra_core_storage.TABLE_MEMORY_RUN_FENCES);
+		try {
+			return await claimTransaction(this.db, async (client) => {
+				const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${fences} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
+				const binds = {
+					runId: fence.runId,
+					generation: fence.generation,
+					ownerId: fence.ownerId
+				};
+				if (!row) {
+					await client.none(`INSERT INTO ${fences} ("runId", generation, "ownerId") VALUES (:runId, :generation, :ownerId)`, binds);
+					return true;
+				}
+				const generation = Number(row.generation);
+				if (!(generation < fence.generation) && !(generation === fence.generation && String(row.ownerId) === fence.ownerId)) return false;
+				await client.none(`UPDATE ${fences} SET generation = :generation, "ownerId" = :ownerId, "retiredAt" = NULL WHERE "runId" = :runId`, binds);
+				return true;
+			});
+		} catch (error) {
+			throw storageError$1("RAISE_RUN_FENCE", "FAILED", { runId: fence.runId }, error);
+		}
+	}
+	async retireRunFence(fence) {
+		const fences = table(this.ctx, _mastra_core_storage.TABLE_MEMORY_RUN_FENCES);
+		try {
+			return await this.db.tx(async (client) => {
+				const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${fences} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
+				if (!row || Number(row.generation) !== fence.generation || String(row.ownerId) !== fence.ownerId) return false;
+				await client.none(`UPDATE ${fences} SET "retiredAt" = ${DB_NOW_MS} WHERE "runId" = :runId`, { runId: fence.runId });
+				return true;
+			});
+		} catch (error) {
+			throw storageError$1("RETIRE_RUN_FENCE", "FAILED", { runId: fence.runId }, error);
+		}
 	}
 	async getThreadById(args) {
 		return getThreadById(this.ctx, args);
 	}
-	async saveThread(args) {
-		return saveThread(this.ctx, args);
+	async saveThread({ fence, ...args }) {
+		return saveThread(this.ctx, {
+			...args,
+			fence: (0, _mastra_core_storage.resolveRunFence)(this, fence)
+		});
 	}
-	async updateThread(args) {
-		return updateThread(this.ctx, args);
+	async updateThread({ fence, ...args }) {
+		return updateThread(this.ctx, {
+			...args,
+			fence: (0, _mastra_core_storage.resolveRunFence)(this, fence)
+		});
 	}
 	async deleteThread(args) {
 		return deleteThread(this.ctx, args);
@@ -5489,14 +5849,20 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 	async listMessagesByResourceId(args) {
 		return listMessagesByResourceId(this.ctx, args);
 	}
-	async saveMessages(args) {
-		return saveMessages(this.ctx, args);
+	async saveMessages({ fence, ...args }) {
+		return saveMessages(this.ctx, {
+			...args,
+			fence: (0, _mastra_core_storage.resolveRunFence)(this, fence)
+		});
 	}
-	async updateMessages(args) {
-		return updateMessages(this.ctx, args);
+	async updateMessages({ fence, ...args }) {
+		return updateMessages(this.ctx, {
+			...args,
+			fence: (0, _mastra_core_storage.resolveRunFence)(this, fence)
+		});
 	}
-	async deleteMessages(messageIds) {
-		return deleteMessages(this.ctx, messageIds);
+	async deleteMessages(messageIds, options) {
+		return deleteMessages(this.ctx, messageIds, (0, _mastra_core_storage.resolveRunFence)(this, options?.fence));
 	}
 	async getResourceById(args) {
 		return getResourceById(this.ctx, args);
@@ -5504,8 +5870,11 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 	async saveResource(args) {
 		return saveResource(this.ctx, args);
 	}
-	async updateResource(args) {
-		return updateResource(this.ctx, args);
+	async updateResource({ fence, ...args }) {
+		return updateResource(this.ctx, {
+			...args,
+			fence: (0, _mastra_core_storage.resolveRunFence)(this, fence)
+		});
 	}
 	async cloneThread(args) {
 		const sourceThread = await this.getThreadById({ threadId: args.sourceThreadId });
@@ -5595,10 +5964,13 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 		return insertObservationalMemoryRecord(this.ctx, record);
 	}
 	async updateActiveObservations(input) {
-		return updateActiveObservations(this.ctx, input);
+		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
+	}
+	async commitActiveObservations(input) {
+		return updateActiveObservations(this.ctx, input, (0, _mastra_core_storage.resolveRunFence)(this, void 0));
 	}
 	async createReflectionGeneration(input) {
-		return createReflectionGeneration(this.ctx, input);
+		return createReflectionGeneration(this.ctx, input, (0, _mastra_core_storage.resolveRunFence)(this, void 0));
 	}
 	async setReflectingFlag(id, isReflecting) {
 		return setReflectingFlag(this.ctx, id, isReflecting);
@@ -5622,16 +5994,19 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
 		return updateObservationalMemoryConfig(this.ctx, input);
 	}
 	async updateBufferedObservations(input) {
-		return updateBufferedObservations(this.ctx, input);
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
+		return updateBufferedObservations(this.ctx, input, (0, _mastra_core_storage.resolveRunFence)(this, void 0));
 	}
 	async swapBufferedToActive(input) {
-		return swapBufferedToActive(this.ctx, input);
+		return swapBufferedToActive(this.ctx, input, (0, _mastra_core_storage.resolveRunFence)(this, void 0));
 	}
 	async updateBufferedReflection(input) {
-		return updateBufferedReflection(this.ctx, input);
+		return updateBufferedReflection(this.ctx, input, (0, _mastra_core_storage.resolveRunFence)(this, void 0));
 	}
 	async swapBufferedReflectionToActive(input) {
-		return swapBufferedReflectionToActive(this.ctx, input);
+		return swapBufferedReflectionToActive(this.ctx, input, (0, _mastra_core_storage.resolveRunFence)(this, void 0));
 	}
 };
 //#endregion
@@ -7976,8 +8351,19 @@ const STORE_NAME$1 = "ORACLEDB";
 const WORKFLOW_CREATED_AT = "\"createdAt\"";
 const WORKFLOW_UPDATED_AT = "\"updatedAt\"";
 const WORKFLOW_RESOURCE_ID = "\"resourceId\"";
+const RUN_OWNER_COLUMNS = `generation AS "generation", "ownerId", "leaseExpiresAt", ${DB_NOW_MS} AS "nowMs"`;
+function toRunOwnershipRecord(runId, row) {
+	const leaseExpiresAt = row.leaseExpiresAt === null ? null : Number(row.leaseExpiresAt);
+	return {
+		runId,
+		generation: Number(row.generation),
+		ownerId: String(row.ownerId),
+		leaseExpiresAt: leaseExpiresAt === null ? null : new Date(leaseExpiresAt),
+		live: leaseExpiresAt !== null && leaseExpiresAt > Number(row.nowMs)
+	};
+}
 var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.WorkflowsStorage {
-	static MANAGED_TABLES = [_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT];
+	static MANAGED_TABLES = [_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS];
 	db;
 	schemaName;
 	skipDefaultIndexes;
@@ -7998,10 +8384,114 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 	}
 	async dangerouslyClearAll() {
 		await this.db.clearTable(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT);
+		await this.db.clearTable(_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS);
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async claimRunOwnership({ runId, ownerId, leaseMs, force, expectedGeneration }) {
+		const table = this.runOwnersTable();
+		try {
+			return await claimTransaction(this.db, async (client) => {
+				const existing = await client.oneOrNone(`SELECT generation AS "generation" FROM ${table} WHERE "runId" = :runId FOR UPDATE`, { runId });
+				if (!existing) {
+					if (expectedGeneration !== void 0 && expectedGeneration !== 0) return {
+						acquired: false,
+						record: null
+					};
+					await client.none(`INSERT INTO ${table} ("runId", generation, "ownerId", "leaseExpiresAt", "updatedAt")
+             VALUES (:runId, ${DB_NOW_MS}, :ownerId, ${DB_NOW_MS} + :leaseMs, ${DB_NOW_MS})`, {
+						runId,
+						ownerId,
+						leaseMs
+					});
+					return {
+						acquired: true,
+						record: await this.readRunOwner(client, runId)
+					};
+				}
+				await client.none(`UPDATE ${table}
+           SET generation = generation + 1, "ownerId" = :ownerId, "leaseExpiresAt" = ${DB_NOW_MS} + :leaseMs,
+               "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = :runId
+             AND (:expectedGeneration IS NULL OR generation = :expectedGeneration)
+             AND (:force = 1 OR "leaseExpiresAt" IS NULL OR "leaseExpiresAt" <= ${DB_NOW_MS})`, {
+					runId,
+					ownerId,
+					leaseMs,
+					expectedGeneration: expectedGeneration ?? null,
+					force: force === true ? 1 : 0
+				});
+				const record = await this.readRunOwner(client, runId);
+				return record && record.generation === Number(existing.generation) + 1 ? {
+					acquired: true,
+					record
+				} : {
+					acquired: false,
+					record
+				};
+			});
+		} catch (error) {
+			throw this.storageError("CLAIM_RUN_OWNERSHIP", "FAILED", { runId }, error);
+		}
+	}
+	async renewRunOwnership({ leaseMs, ...fence }) {
+		try {
+			return await this.db.tx(async (client) => {
+				await client.none(`UPDATE ${this.runOwnersTable()}
+           SET "leaseExpiresAt" = ${DB_NOW_MS} + :leaseMs, "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = :runId AND generation = :generation AND "ownerId" = :ownerId
+             AND "leaseExpiresAt" IS NOT NULL`, {
+					runId: fence.runId,
+					generation: fence.generation,
+					ownerId: fence.ownerId,
+					leaseMs
+				});
+				const record = await this.readRunOwner(client, fence.runId);
+				return record !== null && record.generation === fence.generation && record.ownerId === fence.ownerId && record.leaseExpiresAt !== null ? {
+					renewed: true,
+					record
+				} : {
+					renewed: false,
+					record
+				};
+			});
+		} catch (error) {
+			throw this.storageError("RENEW_RUN_OWNERSHIP", "FAILED", { runId: fence.runId }, error);
+		}
+	}
+	async releaseRunOwnership(fence) {
+		try {
+			return await this.db.tx(async (client) => {
+				await client.none(`UPDATE ${this.runOwnersTable()} SET "leaseExpiresAt" = NULL, "updatedAt" = ${DB_NOW_MS}
+           WHERE "runId" = :runId AND generation = :generation AND "ownerId" = :ownerId`, {
+					runId: fence.runId,
+					generation: fence.generation,
+					ownerId: fence.ownerId
+				});
+				const record = await this.readRunOwner(client, fence.runId);
+				return record !== null && record.generation === fence.generation && record.ownerId === fence.ownerId;
+			});
+		} catch (error) {
+			throw this.storageError("RELEASE_RUN_OWNERSHIP", "FAILED", { runId: fence.runId }, error);
+		}
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
+	async getRunOwnership({ runId }) {
+		try {
+			return await this.readRunOwner(this.db, runId);
+		} catch (error) {
+			throw this.storageError("GET_RUN_OWNERSHIP", "FAILED", { runId }, error);
+		}
+	}
+	async readRunOwner(client, runId) {
+		const row = await client.oneOrNone(`SELECT ${RUN_OWNER_COLUMNS} FROM ${this.runOwnersTable()} WHERE "runId" = :runId`, { runId });
+		return row ? toRunOwnershipRecord(runId, row) : null;
+	}
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence, runId);
 		try {
 			return await this.db.tx(async (client) => {
+				if (fence) await assertRunFence(client, this.runOwnersTable(), fence, "updateWorkflowResults");
 				await this.ensureWorkflowRunRow(client, workflowName, runId);
 				const existing = await client.one(`SELECT snapshot AS "snapshot", ${WORKFLOW_RESOURCE_ID} AS "resourceId" FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId FOR UPDATE`, {
 					workflowName,
@@ -8025,6 +8515,7 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 				return snapshot.context;
 			});
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw this.storageError("UPDATE_WORKFLOW_RESULTS", "FAILED", {
 				workflowName,
 				runId,
@@ -8032,9 +8523,11 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 			}, error);
 		}
 	}
-	async updateWorkflowState({ workflowName, runId, opts }) {
+	async updateWorkflowState({ workflowName, runId, opts, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence, runId);
 		try {
 			return await this.db.tx(async (client) => {
+				if (fence) await assertRunFence(client, this.runOwnersTable(), fence, "updateWorkflowState");
 				const existing = await client.oneOrNone(`SELECT snapshot AS "snapshot" FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId FOR UPDATE`, {
 					workflowName,
 					runId
@@ -8057,24 +8550,26 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 				return updatedSnapshot;
 			});
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw this.storageError("UPDATE_WORKFLOW_STATE", "FAILED", {
 				workflowName,
 				runId
 			}, error);
 		}
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
 		try {
 			const now = /* @__PURE__ */ new Date();
-			await this.db.none(this.workflowMergeSql(), {
+			await withRunFence(this.db, this.runOwnersTable(), (0, _mastra_core_storage.resolveRunFence)(this, fence, runId), "persistWorkflowSnapshot", (client) => client.none(this.workflowMergeSql(), {
 				workflowName,
 				runId,
 				resourceId: resourceId ?? null,
 				snapshot: jsonBind(snapshot),
 				createdAt: createdAt ?? now,
 				updatedAt: updatedAt ?? now
-			});
+			}));
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw this.storageError("PERSIST_WORKFLOW_SNAPSHOT", "FAILED", {
 				workflowName,
 				runId
@@ -8138,13 +8633,14 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 			}, error);
 		}
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
 		try {
-			await this.db.none(`DELETE FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId`, {
+			await withRunFence(this.db, this.runOwnersTable(), (0, _mastra_core_storage.resolveRunFence)(this, fence, runId), "deleteWorkflowRunById", (client) => client.none(`DELETE FROM ${this.table()} WHERE workflow_name = :workflowName AND run_id = :runId`, {
 				workflowName,
 				runId
-			});
+			}));
 		} catch (error) {
+			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw this.storageError("DELETE_WORKFLOW_RUN_BY_ID", "FAILED", {
 				runId,
 				workflowName
@@ -8163,6 +8659,10 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
         CONSTRAINT ${this.constraint("MASTRA_WORKFLOW_SNAPSHOT_PK")} PRIMARY KEY (workflow_name, run_id)
       )`, [-955]);
 		await this.db.executeDdl(`ALTER TABLE ${this.table()} ADD (${WORKFLOW_RESOURCE_ID} VARCHAR2(512))`, [-1430]);
+		await this.db.createTable({
+			tableName: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS,
+			schema: _mastra_core_storage.RUN_FENCING_TABLE_SCHEMAS[_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS]
+		});
 	}
 	async createIndexes() {
 		await this.db.withConnection(async (connection) => {
@@ -8300,6 +8800,9 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
 	table() {
 		return qualifyName(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, this.schemaName);
 	}
+	runOwnersTable() {
+		return qualifyName(_mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS, this.schemaName);
+	}
 	indexName(indexName) {
 		return indexNameForTable(indexName, "IDX");
 	}
@@ -8501,7 +9004,7 @@ function checksumMigration(input) {
 //#region src/storage/index.ts
 const STORE_NAME = "ORACLEDB";
 const DOMAIN_SCHEMA_VERSIONS = {
-	R001_MEMORY_SCHEMA: 1,
+	R001_MEMORY_SCHEMA: 2,
 	R002_WORKFLOWS_SCHEMA: 1,
 	R003_OBSERVABILITY_SCHEMA: 1,
 	R004_SCORES_SCHEMA: 1,
@@ -8589,6 +9092,10 @@ var OracleStore = class extends _mastra_core_storage.MastraCompositeStore {
 	async runMigrations(forceRepeatable) {
 		try {
 			const results = await this.migrationRegistry.run(this.storageMigrations(), { forceRepeatable });
+			if (results.find((result) => result.id === "R001_MEMORY_SCHEMA")?.status === "skipped") {
+				const memory = this.stores.memory;
+				if (memory instanceof MemoryOracle) await memory.backfillObservationalMemorySupersededBy();
+			}
 			this.isInitialized = true;
 			return results;
 		} catch (error) {