@mastra/convex 1.7.2 → 1.7.3-alpha.1

package/dist/index.js

@@ -1,7 +1,7 @@
-import { a as mastraCache, i as mastraStorage, n as mastraNativeVectorMutation, r as mastraNativeVectorQuery, t as mastraNativeVectorAction } from "./server-D3SG5LQf.js";
+import { a as mastraCache, i as mastraStorage, n as mastraNativeVectorMutation, r as mastraNativeVectorQuery, t as mastraNativeVectorAction } from "./server-B8RSiOmu.js";
 import { TABLE_BACKGROUND_TASKS, TABLE_CHANNEL_CONFIG, TABLE_CHANNEL_INSTALLATIONS, TABLE_MESSAGES, TABLE_OBSERVATIONAL_MEMORY, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCORERS, TABLE_THREADS, TABLE_WORKFLOW_SNAPSHOT, defineMastraNativeVectorTable, mastraBackgroundTasksTable, mastraCacheListItemsTable, mastraCacheTable, mastraChannelConfigTable, mastraChannelInstallationsTable, mastraDocumentsTable, mastraMessagesTable, mastraObservationalMemoryTable, mastraResourcesTable, mastraScheduleTriggersTable, mastraSchedulesTable, mastraScoresTable, mastraThreadsTable, mastraVectorIndexesTable, mastraVectorsTable, mastraWorkflowSnapshotsTable } from "./schema.js";
 import { MastraServerCache } from "@mastra/core/cache";
-import { BackgroundTasksStorage, ChannelsStorage, MastraCompositeStore, MemoryStorage, SchedulesStorage, ScoresStorage, TABLE_BACKGROUND_TASKS as TABLE_BACKGROUND_TASKS$1, TABLE_CHANNEL_CONFIG as TABLE_CHANNEL_CONFIG$1, TABLE_CHANNEL_INSTALLATIONS as TABLE_CHANNEL_INSTALLATIONS$1, TABLE_MESSAGES as TABLE_MESSAGES$1, TABLE_RESOURCES as TABLE_RESOURCES$1, TABLE_SCHEDULES as TABLE_SCHEDULES$1, TABLE_SCHEDULE_TRIGGERS as TABLE_SCHEDULE_TRIGGERS$1, TABLE_SCORERS as TABLE_SCORERS$1, TABLE_THREADS as TABLE_THREADS$1, TABLE_WORKFLOW_SNAPSHOT as TABLE_WORKFLOW_SNAPSHOT$1, WorkflowsStorage, calculatePagination, createStorageErrorId, createVectorErrorId, filterByDateRange, normalizePerPage, normalizeScheduleTarget, safelyParseJSON, storageMessageMatchesMetadataFilter, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { BackgroundTasksStorage, ChannelsStorage, MastraCompositeStore, MemoryStorage, RUN_FENCE_CONFLICT_ERROR_ID, RunFenceConflictError, SchedulesStorage, ScoresStorage, TABLE_BACKGROUND_TASKS as TABLE_BACKGROUND_TASKS$1, TABLE_CHANNEL_CONFIG as TABLE_CHANNEL_CONFIG$1, TABLE_CHANNEL_INSTALLATIONS as TABLE_CHANNEL_INSTALLATIONS$1, TABLE_MEMORY_RUN_FENCES, TABLE_MESSAGES as TABLE_MESSAGES$1, TABLE_RESOURCES as TABLE_RESOURCES$1, TABLE_SCHEDULES as TABLE_SCHEDULES$1, TABLE_SCHEDULE_TRIGGERS as TABLE_SCHEDULE_TRIGGERS$1, TABLE_SCORERS as TABLE_SCORERS$1, TABLE_THREADS as TABLE_THREADS$1, TABLE_WORKFLOW_RUN_OWNERS, TABLE_WORKFLOW_SNAPSHOT as TABLE_WORKFLOW_SNAPSHOT$1, WorkflowsStorage, calculatePagination, createStorageErrorId, createVectorErrorId, filterByDateRange, normalizePerPage, normalizeScheduleTarget, resolveRunFence, safelyParseJSON, storageMessageMatchesMetadataFilter, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { MastraBase } from "@mastra/core/base";
 import { MessageList } from "@mastra/core/agent";
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
@@ -252,6 +252,154 @@ var ConvexAdminClient = class {
 	}
 };
 //#endregion
+//#region src/storage/run-fencing.ts
+const READ_OPS = /* @__PURE__ */ new Set([
+	"load",
+	"loadMany",
+	"queryTable",
+	"omGetLatest",
+	"omGetHistory",
+	"listDueSchedules",
+	"listScheduleTriggers"
+]);
+async function callRunClaim(client, request, operation) {
+	try {
+		return await client.callStorageRaw(request);
+	} catch (error) {
+		const { code, message } = error;
+		if (code === RUN_FENCE_CONFLICT_ERROR_ID && request.op === "fenced") throw new RunFenceConflictError(request.fence, operation);
+		if (typeof message === "string" && message.startsWith(`Unsupported operation ${request.op}`)) throw new Error(`The deployed Convex storage function does not support run fencing (${request.op}). Redeploy your Convex functions with the installed version of @mastra/convex.`, { cause: error });
+		throw error;
+	}
+}
+/** Sends writes inside a fenced operation, so each is applied only while `check.fence` holds the run. */
+var FencedStorageCaller = class {
+	client;
+	check;
+	constructor(client, check) {
+		this.client = client;
+		this.check = check;
+	}
+	callStorageRaw(request) {
+		if (READ_OPS.has(request.op)) return this.client.callStorageRaw(request);
+		return callRunClaim(this.client, {
+			op: "fenced",
+			tableName: this.check.claims,
+			fence: toFence(this.check.fence),
+			request
+		}, this.check.operation);
+	}
+	async callStorage(request) {
+		return (await this.callStorageRaw(request)).result;
+	}
+};
+/** The client, or one that fences every write when `check` is set. */
+function fencedCaller(client, check) {
+	return check ? new FencedStorageCaller(client, check) : client;
+}
+/**
+* Rejects a fenced write that turns out to have nothing to write when its
+* fence is no longer current, as the write itself would have been rejected.
+*/
+async function assertRunFence(client, check) {
+	if (!check) return;
+	await callRunClaim(client, {
+		op: "fenced",
+		tableName: check.claims,
+		fence: toFence(check.fence)
+	}, check.operation);
+}
+function toFence({ runId, generation, ownerId }) {
+	return {
+		runId,
+		generation,
+		ownerId
+	};
+}
+function toRecord(claim, now) {
+	if (!claim) return null;
+	const { runId, generation, ownerId, leaseExpiresAt } = claim;
+	return {
+		runId,
+		generation,
+		ownerId,
+		leaseExpiresAt: leaseExpiresAt === null ? null : new Date(leaseExpiresAt),
+		live: leaseExpiresAt !== null && leaseExpiresAt > now
+	};
+}
+async function ownerOperation(client, request) {
+	const { result } = await callRunClaim(client, request, request.op);
+	return {
+		applied: result.applied,
+		record: toRecord(result.claim, result.now)
+	};
+}
+async function claimRunOwnership(client, { runId, ownerId, leaseMs, force, expectedGeneration }) {
+	const { applied, record } = await ownerOperation(client, {
+		op: "claimRunOwnership",
+		tableName: TABLE_WORKFLOW_RUN_OWNERS,
+		runId,
+		ownerId,
+		leaseMs,
+		force: force ?? false,
+		...expectedGeneration !== void 0 ? { expectedGeneration } : {}
+	});
+	return applied ? {
+		acquired: true,
+		record
+	} : {
+		acquired: false,
+		record
+	};
+}
+async function renewRunOwnership(client, { leaseMs, ...fence }) {
+	const { applied, record } = await ownerOperation(client, {
+		op: "renewRunOwnership",
+		tableName: TABLE_WORKFLOW_RUN_OWNERS,
+		fence: toFence(fence),
+		leaseMs
+	});
+	return applied ? {
+		renewed: true,
+		record
+	} : {
+		renewed: false,
+		record
+	};
+}
+async function releaseRunOwnership(client, fence) {
+	const { applied } = await ownerOperation(client, {
+		op: "releaseRunOwnership",
+		tableName: TABLE_WORKFLOW_RUN_OWNERS,
+		fence: toFence(fence)
+	});
+	return applied;
+}
+async function getRunOwnership(client, runId) {
+	const { record } = await ownerOperation(client, {
+		op: "getRunOwnership",
+		tableName: TABLE_WORKFLOW_RUN_OWNERS,
+		runId
+	});
+	return record;
+}
+async function raiseRunFence(client, fence) {
+	const { applied } = await ownerOperation(client, {
+		op: "raiseRunFence",
+		tableName: TABLE_MEMORY_RUN_FENCES,
+		fence: toFence(fence)
+	});
+	return applied;
+}
+async function retireRunFence(client, fence) {
+	const { applied } = await ownerOperation(client, {
+		op: "retireRunFence",
+		tableName: TABLE_MEMORY_RUN_FENCES,
+		fence: toFence(fence)
+	});
+	return applied;
+}
+//#endregion
 //#region src/storage/types.ts
 /**
 * Observational memory table name. Defined locally (not value-imported from
@@ -270,11 +418,17 @@ function resolveConvexConfig(config) {
 	if ("client" in config) return config.client;
 	return new ConvexAdminClient(config);
 }
-var ConvexDB = class extends MastraBase {
+var ConvexDB = class ConvexDB extends MastraBase {
+	adminClient;
 	client;
-	constructor(client) {
+	constructor(adminClient, check) {
 		super({ name: "convex-db" });
-		this.client = client;
+		this.adminClient = adminClient;
+		this.client = fencedCaller(adminClient, check);
+	}
+	/** This store with every write applied only while `check.fence` holds the run, or itself without a check. */
+	fenced(check) {
+		return check ? new ConvexDB(this.adminClient, check) : this;
 	}
 	async hasColumn(_table, _column) {
 		return true;
@@ -487,15 +641,43 @@ var ConvexDB = class extends MastraBase {
 			...args
 		});
 	}
-	async omUpdateActive(args) {
+	async omInitialize(record) {
+		return this.client.callStorage({
+			op: "omInitialize",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			record
+		});
+	}
+	async omCreateReflectionGeneration(args) {
+		return this.client.callStorage({
+			op: "omCreateReflectionGeneration",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			...args
+		});
+	}
+	async omSetPendingMessageTokens(args) {
 		await this.client.callStorage({
+			op: "omSetPendingMessageTokens",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			...args
+		});
+	}
+	async omSetBufferingObservationFlag(args) {
+		await this.client.callStorage({
+			op: "omSetBufferingObservationFlag",
+			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
+			...args
+		});
+	}
+	async omUpdateActive(args) {
+		return this.client.callStorage({
 			op: "omUpdateActive",
 			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
 			...args
 		});
 	}
 	async omAppendBufferedChunk(args) {
-		await this.client.callStorage({
+		return this.client.callStorage({
 			op: "omAppendBufferedChunk",
 			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
 			...args
@@ -900,6 +1082,17 @@ var ChannelsConvex = class extends ChannelsStorage {
 	}
 };
 //#endregion
+//#region ../../packages/_internal-core/dist/memory/index.js
+/**
+* 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`);
+}
+//#endregion
 //#region src/storage/domains/memory/index.ts
 function parseStoredThread(row) {
 	return {
@@ -975,7 +1168,8 @@ function parseStoredOMRecord(doc) {
 		config: config ?? {},
 		metadata: metadata ?? void 0,
 		observedMessageIds: doc.observedMessageIds || void 0,
-		observedTimezone: doc.observedTimezone || void 0
+		observedTimezone: doc.observedTimezone || void 0,
+		supersededBy: doc.supersededBy ?? null
 	};
 }
 var MemoryConvex = class extends MemoryStorage {
@@ -983,10 +1177,32 @@ var MemoryConvex = class extends MemoryStorage {
 	supportsObservationalMemory = true;
 	supportsObservationalMemoryHistorySearch = true;
 	#db;
+	#client;
 	constructor(config) {
 		super();
-		const client = resolveConvexConfig(config);
-		this.#db = new ConvexDB(client);
+		this.#client = resolveConvexConfig(config);
+		this.#db = new ConvexDB(this.#client);
+	}
+	supportsRunFencing() {
+		return true;
+	}
+	async raiseRunFence(fence) {
+		return raiseRunFence(this.#client, fence);
+	}
+	async retireRunFence(fence) {
+		return retireRunFence(this.#client, fence);
+	}
+	#runFenceCheck(fence, operation) {
+		const resolved = resolveRunFence(this, fence);
+		return resolved && {
+			claims: TABLE_MEMORY_RUN_FENCES,
+			fence: resolved,
+			operation
+		};
+	}
+	/** The store to write through: fenced when the write carries or inherits a fence. */
+	#dbFor(fence, operation) {
+		return this.#db.fenced(this.#runFenceCheck(fence, operation));
 	}
 	async init() {}
 	async dangerouslyClearAll() {
@@ -994,6 +1210,7 @@ var MemoryConvex = class extends MemoryStorage {
 		await this.#db.clearTable({ tableName: TABLE_MESSAGES$1 });
 		await this.#db.clearTable({ tableName: TABLE_RESOURCES$1 });
 		await this.#db.clearTable({ tableName: TABLE_OBSERVATIONAL_MEMORY$1 });
+		await this.#db.clearTable({ tableName: TABLE_MEMORY_RUN_FENCES });
 	}
 	async getThreadById({ threadId, resourceId }) {
 		const row = await this.#db.load({
@@ -1003,8 +1220,8 @@ var MemoryConvex = class extends MemoryStorage {
 		if (!row || resourceId !== void 0 && row.resourceId !== resourceId) return null;
 		return parseStoredThread(row);
 	}
-	async saveThread({ thread }) {
-		await this.#db.insert({
+	async saveThread({ thread, fence }) {
+		await this.#dbFor(fence, "saveThread").insert({
 			tableName: TABLE_THREADS$1,
 			record: {
 				...thread,
@@ -1013,8 +1230,8 @@ var MemoryConvex = class extends MemoryStorage {
 		});
 		return thread;
 	}
-	async updateThread({ id, title, metadata }) {
-		const updated = await this.#db.updateThread({
+	async updateThread({ id, title, metadata, fence }) {
+		const updated = await this.#dbFor(fence, "updateThread").updateThread({
 			id,
 			title,
 			metadata,
@@ -1204,8 +1421,9 @@ var MemoryConvex = class extends MemoryStorage {
 		const filtered = (await this.#db.loadMany(TABLE_MESSAGES$1, messageIds)).map((row) => this.parseStoredMessage(row));
 		return { messages: new MessageList().add(filtered, "memory").get.all.db() };
 	}
-	async saveMessages({ messages }) {
+	async saveMessages({ messages, fence }) {
 		if (messages.length === 0) return { messages: [] };
+		const db = this.#dbFor(fence, "saveMessages");
 		const normalized = messages.map((message) => {
 			if (!message.threadId) throw new Error("Thread ID is required");
 			if (!message.resourceId) throw new Error("Resource ID is required");
@@ -1220,21 +1438,23 @@ var MemoryConvex = class extends MemoryStorage {
 				resourceId: message.resourceId
 			};
 		});
-		await this.#db.batchInsert({
+		await db.batchInsert({
 			tableName: TABLE_MESSAGES$1,
 			records: normalized
 		});
 		const threadIds = [...new Set(messages.map((m) => m.threadId).filter(Boolean))];
 		const now = /* @__PURE__ */ new Date();
-		for (const threadId of threadIds) await this.#db.patch({
+		for (const threadId of threadIds) await db.patch({
 			tableName: TABLE_THREADS$1,
 			id: threadId,
 			record: { updatedAt: now.toISOString() }
 		});
 		return { messages: new MessageList().add(messages, "memory").get.all.db() };
 	}
-	async updateMessages({ messages }) {
+	async updateMessages({ messages, fence }) {
 		if (messages.length === 0) return [];
+		const check = this.#runFenceCheck(fence, "updateMessages");
+		const db = this.#db.fenced(check);
 		const existingRows = await this.#db.loadMany(TABLE_MESSAGES$1, messages.map((message) => message.id));
 		const existing = new Map(existingRows.map((row) => [row.id, row]));
 		const updated = [];
@@ -1262,22 +1482,26 @@ var MemoryConvex = class extends MemoryStorage {
 				};
 				current.content = JSON.stringify(mergedContent);
 			}
-			await this.#db.insert({
+			await db.insert({
 				tableName: TABLE_MESSAGES$1,
 				record: current
 			});
 			updated.push(this.parseStoredMessage(current));
 		}
+		if (updated.length === 0) {
+			await assertRunFence(this.#client, check);
+			return updated;
+		}
 		const now = /* @__PURE__ */ new Date();
-		for (const threadId of affectedThreadIds) await this.#db.patch({
+		for (const threadId of affectedThreadIds) await db.patch({
 			tableName: TABLE_THREADS$1,
 			id: threadId,
 			record: { updatedAt: now.toISOString() }
 		});
 		return updated;
 	}
-	async deleteMessages(messageIds) {
-		await this.#db.deleteMany(TABLE_MESSAGES$1, messageIds);
+	async deleteMessages(messageIds, options) {
+		await this.#dbFor(options?.fence, "deleteMessages").deleteMany(TABLE_MESSAGES$1, messageIds);
 	}
 	async saveResource({ resource }) {
 		const record = {
@@ -1300,9 +1524,9 @@ var MemoryConvex = class extends MemoryStorage {
 		if (!record) return null;
 		return parseStoredResource(record);
 	}
-	async updateResource({ resourceId, workingMemory, metadata }) {
+	async updateResource({ resourceId, workingMemory, metadata, fence }) {
 		const now = /* @__PURE__ */ new Date();
-		return parseStoredResource(await this.#db.updateResource({
+		return parseStoredResource(await this.#dbFor(fence, "updateResource").updateResource({
 			resourceId,
 			workingMemory,
 			metadata,
@@ -1463,9 +1687,9 @@ var MemoryConvex = class extends MemoryStorage {
 		})).map((doc) => parseStoredOMRecord(doc));
 	}
 	async initializeObservationalMemory(input) {
-		const id = crypto.randomUUID();
 		const now = /* @__PURE__ */ new Date();
 		const lookupKey = this.getOMKey(input.threadId, input.resourceId);
+		const id = crypto.randomUUID();
 		const record = {
 			id,
 			scope: input.scope,
@@ -1487,38 +1711,36 @@ var MemoryConvex = class extends MemoryStorage {
 			lastBufferedAtTokens: 0,
 			lastBufferedAtTime: null,
 			config: input.config,
-			observedTimezone: input.observedTimezone
+			observedTimezone: input.observedTimezone,
+			supersededBy: null
 		};
-		await this.#db.insert({
-			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
-			record: {
-				id,
-				lookupKey,
-				scope: input.scope,
-				resourceId: input.resourceId,
-				threadId: input.threadId || null,
-				activeObservations: "",
-				activeObservationsPendingUpdate: null,
-				originType: "initial",
-				config: JSON.stringify(input.config ?? {}),
-				generationCount: 0,
-				lastObservedAt: null,
-				lastReflectionAt: null,
-				pendingMessageTokens: 0,
-				totalTokensObserved: 0,
-				observationTokenCount: 0,
-				isObserving: false,
-				isReflecting: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				observedTimezone: input.observedTimezone || null,
-				createdAt: now.toISOString(),
-				updatedAt: now.toISOString()
-			}
+		const doc = await this.#db.omInitialize({
+			id,
+			lookupKey,
+			scope: input.scope,
+			resourceId: input.resourceId,
+			threadId: input.threadId || null,
+			activeObservations: "",
+			activeObservationsPendingUpdate: null,
+			originType: "initial",
+			config: JSON.stringify(input.config ?? {}),
+			generationCount: 0,
+			lastObservedAt: null,
+			lastReflectionAt: null,
+			pendingMessageTokens: 0,
+			totalTokensObserved: 0,
+			observationTokenCount: 0,
+			isObserving: false,
+			isReflecting: false,
+			isBufferingObservation: false,
+			isBufferingReflection: false,
+			lastBufferedAtTokens: 0,
+			lastBufferedAtTime: null,
+			observedTimezone: input.observedTimezone || null,
+			createdAt: now.toISOString(),
+			updatedAt: now.toISOString()
 		});
-		return record;
+		return doc ? parseStoredOMRecord(doc) : record;
 	}
 	async insertObservationalMemoryRecord(record) {
 		const lookupKey = this.getOMKey(record.threadId, record.resourceId);
@@ -1554,22 +1776,30 @@ var MemoryConvex = class extends MemoryStorage {
 				lastBufferedAtTime: record.lastBufferedAtTime ? toISO(record.lastBufferedAtTime) : null,
 				observedTimezone: record.observedTimezone || null,
 				metadata: record.metadata ? JSON.stringify(record.metadata) : null,
+				supersededBy: record.supersededBy ?? null,
 				createdAt: toISO(record.createdAt),
 				updatedAt: toISO(record.updatedAt)
 			}
 		});
 	}
 	async updateActiveObservations(input) {
-		await this.#db.omUpdateActive({
+		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
+	}
+	async commitActiveObservations(input) {
+		return await this.#dbFor(void 0, "commitActiveObservations").omUpdateActive({
 			id: input.id,
 			observations: input.observations,
 			tokenCount: input.tokenCount,
 			lastObservedAt: toISO(input.lastObservedAt),
 			observedMessageIds: input.observedMessageIds ?? null,
-			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-		});
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...input.expectedActiveObservations !== void 0 ? { expectedActiveObservations: input.expectedActiveObservations } : {}
+		}) ?? { applied: true };
 	}
 	async updateBufferedObservations(input) {
+		await this.appendBufferedObservations(input);
+	}
+	async appendBufferedObservations(input) {
 		const chunk = {
 			id: `ombuf-${crypto.randomUUID()}`,
 			cycleId: input.chunk.cycleId,
@@ -1585,15 +1815,18 @@ var MemoryConvex = class extends MemoryStorage {
 			extractedValues: input.chunk.extractedValues,
 			extractionFailures: input.chunk.extractionFailures
 		};
-		await this.#db.omAppendBufferedChunk({
+		return await this.#dbFor(void 0, "appendBufferedObservations").omAppendBufferedChunk({
 			id: input.id,
 			chunk,
 			lastBufferedAtTime: input.lastBufferedAtTime ? toISO(input.lastBufferedAtTime) : void 0,
 			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-		});
+		}) ?? {
+			persisted: true,
+			recordId: input.id
+		};
 	}
 	async swapBufferedToActive(input) {
-		return this.#db.omSwapBuffered({
+		return this.#dbFor(void 0, "swapBufferedToActive").omSwapBuffered({
 			id: input.id,
 			activationRatio: input.activationRatio,
 			messageTokensThreshold: input.messageTokensThreshold,
@@ -1604,68 +1837,36 @@ var MemoryConvex = class extends MemoryStorage {
 			now: (/* @__PURE__ */ new Date()).toISOString()
 		});
 	}
-	async createReflectionGeneration(input) {
-		const id = crypto.randomUUID();
-		const now = /* @__PURE__ */ new Date();
-		const lookupKey = this.getOMKey(input.currentRecord.threadId, input.currentRecord.resourceId);
-		const record = {
-			id,
-			scope: input.currentRecord.scope,
-			threadId: input.currentRecord.threadId,
-			resourceId: input.currentRecord.resourceId,
-			createdAt: now,
-			updatedAt: now,
-			lastObservedAt: input.currentRecord.lastObservedAt,
-			originType: "reflection",
-			generationCount: input.currentRecord.generationCount + 1,
-			activeObservations: input.reflection,
-			totalTokensObserved: input.currentRecord.totalTokensObserved,
-			observationTokenCount: input.tokenCount,
-			pendingMessageTokens: 0,
-			isReflecting: false,
-			isObserving: false,
-			isBufferingObservation: false,
-			isBufferingReflection: false,
-			lastBufferedAtTokens: 0,
-			lastBufferedAtTime: null,
-			config: input.currentRecord.config,
-			metadata: input.currentRecord.metadata,
-			observedTimezone: input.currentRecord.observedTimezone
+	/** The caller's snapshot as the server's rollover ops expect it. */
+	#serializeCurrentRecord(currentRecord) {
+		return {
+			id: currentRecord.id,
+			lookupKey: this.getOMKey(currentRecord.threadId, currentRecord.resourceId),
+			scope: currentRecord.scope,
+			threadId: currentRecord.threadId || null,
+			resourceId: currentRecord.resourceId,
+			config: JSON.stringify(currentRecord.config ?? {}),
+			metadata: currentRecord.metadata ? JSON.stringify(currentRecord.metadata) : null,
+			observedTimezone: currentRecord.observedTimezone || null,
+			lastObservedAt: currentRecord.lastObservedAt ? toISO(currentRecord.lastObservedAt) : null,
+			totalTokensObserved: currentRecord.totalTokensObserved,
+			generationCount: currentRecord.generationCount,
+			activeObservations: currentRecord.activeObservations ?? "",
+			observationTokenCount: currentRecord.observationTokenCount ?? 0
 		};
-		await this.#db.insert({
-			tableName: TABLE_OBSERVATIONAL_MEMORY$1,
-			record: {
-				id,
-				lookupKey,
-				scope: record.scope,
-				resourceId: record.resourceId,
-				threadId: record.threadId || null,
-				activeObservations: input.reflection,
-				activeObservationsPendingUpdate: null,
-				originType: "reflection",
-				config: JSON.stringify(record.config ?? {}),
-				generationCount: record.generationCount,
-				lastObservedAt: record.lastObservedAt ? toISO(record.lastObservedAt) : null,
-				lastReflectionAt: now.toISOString(),
-				pendingMessageTokens: 0,
-				totalTokensObserved: record.totalTokensObserved,
-				observationTokenCount: record.observationTokenCount,
-				isObserving: false,
-				isReflecting: false,
-				isBufferingObservation: false,
-				isBufferingReflection: false,
-				lastBufferedAtTokens: 0,
-				lastBufferedAtTime: null,
-				observedTimezone: record.observedTimezone || null,
-				metadata: record.metadata ? JSON.stringify(record.metadata) : null,
-				createdAt: now.toISOString(),
-				updatedAt: now.toISOString()
-			}
+	}
+	async createReflectionGeneration(input) {
+		const doc = await this.#dbFor(void 0, "createReflectionGeneration").omCreateReflectionGeneration({
+			currentRecord: this.#serializeCurrentRecord(input.currentRecord),
+			newId: input.newRecordId ?? crypto.randomUUID(),
+			reflection: input.reflection,
+			tokenCount: input.tokenCount,
+			now: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		return record;
+		return doc ? parseStoredOMRecord(doc) : input.currentRecord;
 	}
 	async updateBufferedReflection(input) {
-		await this.#db.omUpdateBufferedReflection({
+		await this.#dbFor(void 0, "updateBufferedReflection").omUpdateBufferedReflection({
 			id: input.id,
 			reflection: input.reflection,
 			tokenCount: input.tokenCount,
@@ -1675,26 +1876,13 @@ var MemoryConvex = class extends MemoryStorage {
 		});
 	}
 	async swapBufferedReflectionToActive(input) {
-		const { currentRecord } = input;
-		const serializedCurrentRecord = {
-			id: currentRecord.id,
-			lookupKey: this.getOMKey(currentRecord.threadId, currentRecord.resourceId),
-			scope: currentRecord.scope,
-			threadId: currentRecord.threadId || null,
-			resourceId: currentRecord.resourceId,
-			config: JSON.stringify(currentRecord.config ?? {}),
-			metadata: currentRecord.metadata ? JSON.stringify(currentRecord.metadata) : null,
-			observedTimezone: currentRecord.observedTimezone || null,
-			lastObservedAt: currentRecord.lastObservedAt ? toISO(currentRecord.lastObservedAt) : null,
-			totalTokensObserved: currentRecord.totalTokensObserved,
-			generationCount: currentRecord.generationCount
-		};
-		return parseStoredOMRecord(await this.#db.omSwapBufferedReflection({
-			currentRecord: serializedCurrentRecord,
-			newId: crypto.randomUUID(),
+		const doc = await this.#dbFor(void 0, "swapBufferedReflectionToActive").omSwapBufferedReflection({
+			currentRecord: this.#serializeCurrentRecord(input.currentRecord),
+			newId: input.newRecordId ?? crypto.randomUUID(),
 			tokenCount: input.tokenCount,
 			now: (/* @__PURE__ */ new Date()).toISOString()
-		}));
+		});
+		return doc ? parseStoredOMRecord(doc) : input.currentRecord;
 	}
 	async setReflectingFlag(id, isReflecting) {
 		if (!await this.#db.patch({
@@ -1717,15 +1905,12 @@ var MemoryConvex = class extends MemoryStorage {
 		})) throw this.omRecordNotFound("SET_OBSERVING_FLAG", id);
 	}
 	async setBufferingObservationFlag(id, isBuffering, lastBufferedAtTokens) {
-		if (!await this.#db.patch({
-			tableName: "mastra_observational_memory",
+		await this.#db.omSetBufferingObservationFlag({
 			id,
-			record: {
-				isBufferingObservation: isBuffering,
-				...lastBufferedAtTokens !== void 0 ? { lastBufferedAtTokens } : {},
-				updatedAt: /* @__PURE__ */ new Date()
-			}
-		})) throw this.omRecordNotFound("SET_BUFFERING_OBSERVATION_FLAG", id);
+			isBuffering,
+			...lastBufferedAtTokens !== void 0 ? { lastBufferedAtTokens } : {},
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	async setBufferingReflectionFlag(id, isBuffering) {
 		if (!await this.#db.patch({
@@ -1748,14 +1933,11 @@ var MemoryConvex = class extends MemoryStorage {
 				tokenCount
 			}
 		});
-		if (!await this.#db.patch({
-			tableName: "mastra_observational_memory",
+		await this.#db.omSetPendingMessageTokens({
 			id,
-			record: {
-				pendingMessageTokens: tokenCount,
-				updatedAt: /* @__PURE__ */ new Date()
-			}
-		})) throw this.omRecordNotFound("SET_PENDING_MESSAGE_TOKENS", id);
+			tokenCount,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	async clearObservationalMemory(threadId, resourceId) {
 		const lookupKey = this.getOMKey(threadId, resourceId);
@@ -2090,25 +2272,52 @@ var ScoresConvex = class extends ScoresStorage {
 //#region src/storage/domains/workflows/index.ts
 var WorkflowsConvex = class extends WorkflowsStorage {
 	#db;
+	#client;
 	constructor(config) {
 		super();
-		const client = resolveConvexConfig(config);
-		this.#db = new ConvexDB(client);
+		this.#client = resolveConvexConfig(config);
+		this.#db = new ConvexDB(this.#client);
 	}
 	supportsConcurrentUpdates() {
 		return true;
 	}
+	supportsRunFencing() {
+		return true;
+	}
 	async init() {}
 	async dangerouslyClearAll() {
 		await this.#db.clearTable({ tableName: TABLE_WORKFLOW_SNAPSHOT$1 });
+		await this.#db.clearTable({ tableName: TABLE_WORKFLOW_RUN_OWNERS });
+	}
+	/** The store to write a run through: fenced when the write carries or inherits a fence. */
+	#dbFor(fence, runId, operation) {
+		const resolved = resolveRunFence(this, fence, runId);
+		const check = resolved && {
+			claims: TABLE_WORKFLOW_RUN_OWNERS,
+			fence: resolved,
+			operation
+		};
+		return this.#db.fenced(check);
 	}
-	async updateWorkflowResults(args) {
-		return this.#db.mergeWorkflowStepResult(args);
+	async claimRunOwnership(args) {
+		return claimRunOwnership(this.#client, args);
 	}
-	async updateWorkflowState(args) {
-		return this.#db.mergeWorkflowState(args);
+	async renewRunOwnership(args) {
+		return renewRunOwnership(this.#client, args);
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	async releaseRunOwnership(fence) {
+		return releaseRunOwnership(this.#client, fence);
+	}
+	async getRunOwnership({ runId }) {
+		return getRunOwnership(this.#client, runId);
+	}
+	async updateWorkflowResults({ fence, ...args }) {
+		return this.#dbFor(fence, args.runId, "updateWorkflowResults").mergeWorkflowStepResult(args);
+	}
+	async updateWorkflowState({ fence, ...args }) {
+		return this.#dbFor(fence, args.runId, "updateWorkflowState").mergeWorkflowState(args);
+	}
+	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt, fence }) {
 		const now = /* @__PURE__ */ new Date();
 		const existing = await this.#db.load({
 			tableName: TABLE_WORKFLOW_SNAPSHOT$1,
@@ -2117,7 +2326,7 @@ var WorkflowsConvex = class extends WorkflowsStorage {
 				run_id: runId
 			}
 		});
-		await this.#db.insert({
+		await this.#dbFor(fence, runId, "persistWorkflowSnapshot").insert({
 			tableName: TABLE_WORKFLOW_SNAPSHOT$1,
 			record: {
 				workflow_name: workflowName,
@@ -2199,8 +2408,8 @@ var WorkflowsConvex = class extends WorkflowsStorage {
 			resourceId: match.resourceId
 		};
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
-		await this.#db.deleteMany(TABLE_WORKFLOW_SNAPSHOT$1, [`${workflowName}-${runId}`]);
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
+		await this.#dbFor(fence, runId, "deleteWorkflowRunById").deleteMany(TABLE_WORKFLOW_SNAPSHOT$1, [`${workflowName}-${runId}`]);
 	}
 	async getRun(workflowName, runId) {
 		return this.#db.load({