@mastra/convex 1.7.3-alpha.0 → 1.7.3

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-convex
 description: Documentation for @mastra/convex. Use when working with @mastra/convex APIs, configuration, or implementation.
 metadata:
   package: "@mastra/convex"
-  version: "1.7.3-alpha.0"
+  version: "1.7.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.7.3-alpha.0",
+  "version": "1.7.3",
   "package": "@mastra/convex",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-vectors-convex.md

@@ -387,7 +387,6 @@ const results = await vectorStore.query({
 
 | Operator | Description           |
 | -------- | --------------------- |
-| `$eq`    | Equal to              |
 | `$ne`    | Not equal to          |
 | `$gt`    | Greater than          |
 | `$gte`   | Greater than or equal |
@@ -400,10 +399,9 @@ const results = await vectorStore.query({
 
 ## Architecture
 
-`ConvexVector` stores vectors in the `mastra_vectors` table with the following structure:
+`ConvexVector` stores each index in its own table named `mastra_vector_{indexName}`. Each record has the following structure:
 
 - `id`: Unique vector identifier
-- `indexName`: Name of the index
 - `embedding`: The vector data (array of floats)
 - `metadata`: Optional JSON metadata
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server = require("./server-cdXFJzWz.cjs");
+const require_server = require("./server-Bcgr5CcA.cjs");
 const require_schema = require("./schema.cjs");
 let _mastra_core_cache = require("@mastra/core/cache");
 let _mastra_core_storage = require("@mastra/core/storage");
@@ -254,6 +254,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 === _mastra_core_storage.RUN_FENCE_CONFLICT_ERROR_ID && request.op === "fenced") throw new _mastra_core_storage.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: _mastra_core_storage.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: _mastra_core_storage.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: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS,
+		fence: toFence(fence)
+	});
+	return applied;
+}
+async function getRunOwnership(client, runId) {
+	const { record } = await ownerOperation(client, {
+		op: "getRunOwnership",
+		tableName: _mastra_core_storage.TABLE_WORKFLOW_RUN_OWNERS,
+		runId
+	});
+	return record;
+}
+async function raiseRunFence(client, fence) {
+	const { applied } = await ownerOperation(client, {
+		op: "raiseRunFence",
+		tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES,
+		fence: toFence(fence)
+	});
+	return applied;
+}
+async function retireRunFence(client, fence) {
+	const { applied } = await ownerOperation(client, {
+		op: "retireRunFence",
+		tableName: _mastra_core_storage.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
@@ -272,11 +420,17 @@ function resolveConvexConfig(config) {
 	if ("client" in config) return config.client;
 	return new ConvexAdminClient(config);
 }
-var ConvexDB = class extends _mastra_core_base.MastraBase {
+var ConvexDB = class ConvexDB extends _mastra_core_base.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;
@@ -1025,10 +1179,32 @@ var MemoryConvex = class extends _mastra_core_storage.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 = (0, _mastra_core_storage.resolveRunFence)(this, fence);
+		return resolved && {
+			claims: _mastra_core_storage.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() {
@@ -1036,6 +1212,7 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 		await this.#db.clearTable({ tableName: _mastra_core_storage.TABLE_MESSAGES });
 		await this.#db.clearTable({ tableName: _mastra_core_storage.TABLE_RESOURCES });
 		await this.#db.clearTable({ tableName: TABLE_OBSERVATIONAL_MEMORY$1 });
+		await this.#db.clearTable({ tableName: _mastra_core_storage.TABLE_MEMORY_RUN_FENCES });
 	}
 	async getThreadById({ threadId, resourceId }) {
 		const row = await this.#db.load({
@@ -1045,8 +1222,8 @@ var MemoryConvex = class extends _mastra_core_storage.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: _mastra_core_storage.TABLE_THREADS,
 			record: {
 				...thread,
@@ -1055,8 +1232,8 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -1246,8 +1423,9 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 		const filtered = (await this.#db.loadMany(_mastra_core_storage.TABLE_MESSAGES, messageIds)).map((row) => this.parseStoredMessage(row));
 		return { messages: new _mastra_core_agent.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");
@@ -1262,21 +1440,23 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 				resourceId: message.resourceId
 			};
 		});
-		await this.#db.batchInsert({
+		await db.batchInsert({
 			tableName: _mastra_core_storage.TABLE_MESSAGES,
 			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: _mastra_core_storage.TABLE_THREADS,
 			id: threadId,
 			record: { updatedAt: now.toISOString() }
 		});
 		return { messages: new _mastra_core_agent.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(_mastra_core_storage.TABLE_MESSAGES, messages.map((message) => message.id));
 		const existing = new Map(existingRows.map((row) => [row.id, row]));
 		const updated = [];
@@ -1304,22 +1484,26 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 				};
 				current.content = JSON.stringify(mergedContent);
 			}
-			await this.#db.insert({
+			await db.insert({
 				tableName: _mastra_core_storage.TABLE_MESSAGES,
 				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: _mastra_core_storage.TABLE_THREADS,
 			id: threadId,
 			record: { updatedAt: now.toISOString() }
 		});
 		return updated;
 	}
-	async deleteMessages(messageIds) {
-		await this.#db.deleteMany(_mastra_core_storage.TABLE_MESSAGES, messageIds);
+	async deleteMessages(messageIds, options) {
+		await this.#dbFor(options?.fence, "deleteMessages").deleteMany(_mastra_core_storage.TABLE_MESSAGES, messageIds);
 	}
 	async saveResource({ resource }) {
 		const record = {
@@ -1342,9 +1526,9 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -1604,7 +1788,7 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -1633,7 +1817,7 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -1644,7 +1828,7 @@ var MemoryConvex = class extends _mastra_core_storage.MemoryStorage {
 		};
 	}
 	async swapBufferedToActive(input) {
-		return this.#db.omSwapBuffered({
+		return this.#dbFor(void 0, "swapBufferedToActive").omSwapBuffered({
 			id: input.id,
 			activationRatio: input.activationRatio,
 			messageTokensThreshold: input.messageTokensThreshold,
@@ -1674,7 +1858,7 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -1684,7 +1868,7 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -1694,7 +1878,7 @@ var MemoryConvex = class extends _mastra_core_storage.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,
@@ -2090,25 +2274,52 @@ var ScoresConvex = class extends _mastra_core_storage.ScoresStorage {
 //#region src/storage/domains/workflows/index.ts
 var WorkflowsConvex = class extends _mastra_core_storage.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: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT });
+		await this.#db.clearTable({ tableName: _mastra_core_storage.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 = (0, _mastra_core_storage.resolveRunFence)(this, fence, runId);
+		const check = resolved && {
+			claims: _mastra_core_storage.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: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
@@ -2117,7 +2328,7 @@ var WorkflowsConvex = class extends _mastra_core_storage.WorkflowsStorage {
 				run_id: runId
 			}
 		});
-		await this.#db.insert({
+		await this.#dbFor(fence, runId, "persistWorkflowSnapshot").insert({
 			tableName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
 			record: {
 				workflow_name: workflowName,
@@ -2199,8 +2410,8 @@ var WorkflowsConvex = class extends _mastra_core_storage.WorkflowsStorage {
 			resourceId: match.resourceId
 		};
 	}
-	async deleteWorkflowRunById({ runId, workflowName }) {
-		await this.#db.deleteMany(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, [`${workflowName}-${runId}`]);
+	async deleteWorkflowRunById({ runId, workflowName, fence }) {
+		await this.#dbFor(fence, runId, "deleteWorkflowRunById").deleteMany(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, [`${workflowName}-${runId}`]);
 	}
 	async getRun(workflowName, runId) {
 		return this.#db.load({