@mastra/convex 1.7.3-alpha.0 → 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-DozOFGfO.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;
@@ -1023,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() {
@@ -1034,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({
@@ -1043,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,
@@ -1053,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,
@@ -1244,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");
@@ -1260,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 = [];
@@ -1302,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 = {
@@ -1340,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,
@@ -1602,7 +1786,7 @@ var MemoryConvex = class extends MemoryStorage {
 		assertActiveObservationsApplied(await this.commitActiveObservations(input), input.id);
 	}
 	async commitActiveObservations(input) {
-		return await this.#db.omUpdateActive({
+		return await this.#dbFor(void 0, "commitActiveObservations").omUpdateActive({
 			id: input.id,
 			observations: input.observations,
 			tokenCount: input.tokenCount,
@@ -1631,7 +1815,7 @@ var MemoryConvex = class extends MemoryStorage {
 			extractedValues: input.chunk.extractedValues,
 			extractionFailures: input.chunk.extractionFailures
 		};
-		return await this.#db.omAppendBufferedChunk({
+		return await this.#dbFor(void 0, "appendBufferedObservations").omAppendBufferedChunk({
 			id: input.id,
 			chunk,
 			lastBufferedAtTime: input.lastBufferedAtTime ? toISO(input.lastBufferedAtTime) : void 0,
@@ -1642,7 +1826,7 @@ var MemoryConvex = class extends MemoryStorage {
 		};
 	}
 	async swapBufferedToActive(input) {
-		return this.#db.omSwapBuffered({
+		return this.#dbFor(void 0, "swapBufferedToActive").omSwapBuffered({
 			id: input.id,
 			activationRatio: input.activationRatio,
 			messageTokensThreshold: input.messageTokensThreshold,
@@ -1672,7 +1856,7 @@ var MemoryConvex = class extends MemoryStorage {
 		};
 	}
 	async createReflectionGeneration(input) {
-		const doc = await this.#db.omCreateReflectionGeneration({
+		const doc = await this.#dbFor(void 0, "createReflectionGeneration").omCreateReflectionGeneration({
 			currentRecord: this.#serializeCurrentRecord(input.currentRecord),
 			newId: input.newRecordId ?? crypto.randomUUID(),
 			reflection: input.reflection,
@@ -1682,7 +1866,7 @@ var MemoryConvex = class extends MemoryStorage {
 		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,
@@ -1692,7 +1876,7 @@ var MemoryConvex = class extends MemoryStorage {
 		});
 	}
 	async swapBufferedReflectionToActive(input) {
-		const doc = await this.#db.omSwapBufferedReflection({
+		const doc = await this.#dbFor(void 0, "swapBufferedReflectionToActive").omSwapBufferedReflection({
 			currentRecord: this.#serializeCurrentRecord(input.currentRecord),
 			newId: input.newRecordId ?? crypto.randomUUID(),
 			tokenCount: input.tokenCount,
@@ -2088,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 claimRunOwnership(args) {
+		return claimRunOwnership(this.#client, args);
+	}
+	async renewRunOwnership(args) {
+		return renewRunOwnership(this.#client, args);
 	}
-	async updateWorkflowResults(args) {
-		return this.#db.mergeWorkflowStepResult(args);
+	async releaseRunOwnership(fence) {
+		return releaseRunOwnership(this.#client, fence);
 	}
-	async updateWorkflowState(args) {
-		return this.#db.mergeWorkflowState(args);
+	async getRunOwnership({ runId }) {
+		return getRunOwnership(this.#client, runId);
 	}
-	async persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot, createdAt, updatedAt }) {
+	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,
@@ -2115,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,
@@ -2197,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({