@mastra/oracledb 0.5.1 → 0.5.2-alpha.0

package/dist/index.js

@@ -3345,6 +3345,71 @@ 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/domains/memory/utils.ts
 const STORE_NAME$5 = "ORACLEDB";
 const EMPTY_STRING_SENTINEL = "__MASTRA_ORACLE_EMPTY_STRING__";
@@ -3382,6 +3447,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.DB_TYPE_TIMESTAMP_TZ,
+		val: toDate(value)
+	};
+}
 function boolToNumber(value) {
 	return value ? 1 : 0;
 }
@@ -3530,12 +3606,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, 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, TABLE_OBSERVATIONAL_MEMORY)}`);
@@ -3609,7 +3721,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);
@@ -3747,6 +3860,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, TABLE_OBSERVATIONAL_MEMORY)} ADD (${column.name} ${column.type})`, [-1430]);
@@ -4262,14 +4379,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, 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) {
@@ -4301,11 +4419,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 (
@@ -4344,6 +4462,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,
@@ -4365,13 +4484,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, 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 ?? "",
@@ -4393,7 +4521,17 @@ async function insertObservationalMemoryRecord(ctx, record) {
 }
 async function updateActiveObservations(ctx, input) {
 	try {
-		await ctx.db.tx(async (_client, connection) => {
+		return await ctx.db.tx(async (_client, connection) => {
+			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, TABLE_OBSERVATIONAL_MEMORY)}
           SET ${OM_ACTIVE_OBSERVATIONS} = :activeObservations,
@@ -4407,12 +4545,13 @@ 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 MastraError) throw error;
@@ -4420,39 +4559,73 @@ async function updateActiveObservations(ctx, input) {
 	}
 }
 async function createReflectionGeneration(ctx, input) {
+	const { currentRecord } = input;
+	try {
+		return await ctx.db.tx(async (_client, connection) => {
+			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 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, 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");
@@ -4467,9 +4640,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, TABLE_OBSERVATIONAL_MEMORY)}
            SET ${OM_IS_BUFFERING_OBSERVATION} = :isBuffering,
                ${OM_UPDATED_AT} = :updatedAt
@@ -4500,7 +4674,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, 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 MastraError) throw error;
 		throw storageError$1("SET_PENDING_MESSAGE_TOKENS", "FAILED", {
@@ -4522,7 +4706,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) {
@@ -4568,6 +4752,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 (
@@ -4603,6 +4788,7 @@ async function insertOMRecord(ctx, connection, record, timestamp = record.create
       :lastBufferedAtTokens,
       :lastBufferedAtTime,
       :metadata,
+      :supersededBy,
       :createdAt,
       :updatedAt
     )`, {
@@ -4616,8 +4802,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),
@@ -4636,10 +4822,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) {
@@ -4663,7 +4850,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);
 	});
 }
@@ -4701,6 +4888,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"`;
 }
@@ -4736,15 +4924,60 @@ 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, 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, 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) {
 	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) => {
+			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,
@@ -4760,18 +4993,21 @@ 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, 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 MastraError) throw error;
@@ -4782,10 +5018,22 @@ async function swapBufferedToActive(ctx, input) {
 	try {
 		return await ctx.db.tx(async (_client, connection) => {
 			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;
@@ -4803,8 +5051,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;
 		});
@@ -4832,7 +5080,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) {
@@ -4841,66 +5089,32 @@ async function updateBufferedReflection(ctx, input) {
 	}
 }
 async function swapBufferedReflectionToActive(ctx, input) {
+	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"), 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);
+			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"), 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, 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 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, 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,
@@ -5435,6 +5649,15 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 	async init() {
 		await initMemorySchema(this.ctx);
 	}
+	/**
+	* 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);
 	}
@@ -5571,6 +5794,9 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 		return insertObservationalMemoryRecord(this.ctx, record);
 	}
 	async updateActiveObservations(input) {
+		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
+	}
+	async commitActiveObservations(input) {
 		return updateActiveObservations(this.ctx, input);
 	}
 	async createReflectionGeneration(input) {
@@ -5598,6 +5824,9 @@ var MemoryOracle = class MemoryOracle extends MemoryStorage {
 		return updateObservationalMemoryConfig(this.ctx, input);
 	}
 	async updateBufferedObservations(input) {
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
 		return updateBufferedObservations(this.ctx, input);
 	}
 	async swapBufferedToActive(input) {
@@ -8477,7 +8706,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,
@@ -8565,6 +8794,10 @@ var OracleStore = class extends 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) {