@mastra/pg 1.36.0-alpha.2 → 1.36.0-alpha.3

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.36.0-alpha.2",
+  "version": "1.36.0-alpha.3",
   "package": "@mastra/pg",
   "exports": {
     "AgentsPG": {
@@ -55,32 +55,32 @@
     "MemoryPG": {
       "types": "dist/storage/domains/memory/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 11658
+      "line": 11665
     },
     "NotificationsPG": {
       "types": "dist/storage/domains/notifications/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 14469
+      "line": 14562
     },
     "ObservabilityPG": {
       "types": "dist/storage/domains/observability/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 14891
+      "line": 14984
     },
     "ObservabilityStoragePostgresVNext": {
       "types": "dist/storage/domains/observability/v-next/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 21810
+      "line": 21941
     },
     "PGVECTOR_PROMPT": {
       "types": "dist/vector/prompt.d.ts",
       "implementation": "dist/index.js",
-      "line": 28481
+      "line": 28617
     },
     "PgFactoryStorage": {
       "types": "dist/storage/factory-storage.d.ts",
       "implementation": "dist/index.js",
-      "line": 27967
+      "line": 28103
     },
     "PgVector": {
       "types": "dist/vector/index.d.ts",
@@ -95,67 +95,67 @@
     "PostgresStore": {
       "types": "dist/storage/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 28182
+      "line": 28318
     },
     "PostgresStoreVNext": {
       "types": "dist/storage/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 28400
+      "line": 28536
     },
     "PromptBlocksPG": {
       "types": "dist/storage/domains/prompt-blocks/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 22255
+      "line": 22391
     },
     "SchedulesPG": {
       "types": "dist/storage/domains/schedules/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 22882
+      "line": 23018
     },
     "ScorerDefinitionsPG": {
       "types": "dist/storage/domains/scorer-definitions/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 23203
+      "line": 23339
     },
     "ScoresPG": {
       "types": "dist/storage/domains/scores/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 23826
+      "line": 23962
     },
     "SkillsPG": {
       "types": "dist/storage/domains/skills/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 24269
+      "line": 24405
     },
     "ThreadStatePG": {
       "types": "dist/storage/domains/thread-state/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 24960
+      "line": 25096
     },
     "ToolProviderConnectionsPG": {
       "types": "dist/storage/domains/tool-provider-connections/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 25134
+      "line": 25270
     },
     "WorkflowDefinitionsPG": {
       "types": "dist/storage/domains/workflow-definitions/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 25398
+      "line": 25534
     },
     "WorkflowsPG": {
       "types": "dist/storage/domains/workflows/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 25781
+      "line": 25917
     },
     "WorkspacesPG": {
       "types": "dist/storage/domains/workspaces/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 27067
+      "line": 27203
     },
     "exportSchemas": {
       "types": "dist/storage/index.d.ts",
       "implementation": "dist/index.js",
-      "line": 28149
+      "line": 28285
     }
   },
   "modules": {}

package/dist/docs/references/reference-processors-semantic-recall-processor.md

@@ -40,6 +40,8 @@ const processor = new SemanticRecall({
 
 **options.threshold** (`number`): Minimum similarity score threshold (0-1). Messages below this threshold are filtered out
 
+**options.filter** (`VectorFilter`): Metadata filter for the vector query, combined with the scope filter using $and. Messages are stored with their thread's metadata, so the filter can match thread metadata. For example, { projectId: { $eq: 'project-a' } }
+
 **options.indexName** (`string`): Index name for the vector store. If not provided, auto-generated based on embedder model
 
 **options.logger** (`IMastraLogger`): Optional logger instance for structured logging

package/dist/index.cjs

@@ -11678,6 +11678,13 @@ function dedupeMessagesForSave(messages) {
 	}
 	return Array.from(deduped.values());
 }
+/** Shallow merge; keys patched to `undefined` are dropped when serialized. Non-object metadata is replaced. */
+function mergeMetadata(existing, patch) {
+	return {
+		...existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {},
+		...patch
+	};
+}
 var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 	supportsPartialThreadUpdate = true;
 	supportsObservationalMemory = true;
@@ -12244,7 +12251,7 @@ var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 			const createdAt = toUtcISOString(thread.createdAt);
 			const updatedAt = toUtcISOString(thread.updatedAt);
 			const metadataJson = thread.metadata ? toPgJson(thread.metadata) : null;
-			await this.#fenced(fence, "saveThread", (q) => q.none(`INSERT INTO ${tableName} (
+			const saved = await this.#fenced(fence, "saveThread", (q) => q.oneOrNone(`INSERT INTO ${tableName} AS t (
           id,
           "resourceId",
           title,
@@ -12255,13 +12262,12 @@ var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
           "updatedAtZ"
         ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
         ON CONFLICT (id) DO UPDATE SET
-          "resourceId" = EXCLUDED."resourceId",
           title = EXCLUDED.title,
           metadata = EXCLUDED.metadata,
-          "createdAt" = EXCLUDED."createdAt",
-          "createdAtZ" = EXCLUDED."createdAtZ",
           "updatedAt" = EXCLUDED."updatedAt",
-          "updatedAtZ" = EXCLUDED."updatedAtZ"`, [
+          "updatedAtZ" = EXCLUDED."updatedAtZ"
+        WHERE t."resourceId" = EXCLUDED."resourceId"
+        RETURNING *`, [
 				thread.id,
 				thread.resourceId,
 				thread.title,
@@ -12271,12 +12277,26 @@ var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 				updatedAt,
 				updatedAt
 			]));
+			if (!saved) throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "SAVE_THREAD", "RESOURCE_ID_MISMATCH"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.USER,
+				text: `Thread ${thread.id} already exists and belongs to a different resource. Use updateThreadResourceId to move a thread and its messages to another resource.`,
+				details: {
+					threadId: thread.id,
+					resourceId: thread.resourceId
+				}
+			});
 			return {
-				...thread,
-				metadata: metadataJson ? JSON.parse(metadataJson) : thread.metadata
+				id: saved.id,
+				resourceId: saved.resourceId,
+				title: saved.title,
+				metadata: saved.metadata == null ? void 0 : typeof saved.metadata === "string" ? JSON.parse(saved.metadata) : saved.metadata,
+				createdAt: saved.createdAtZ || saved.createdAt,
+				updatedAt: saved.updatedAtZ || saved.updatedAt
 			};
 		} catch (error) {
-			if ((0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
+			if (error instanceof _mastra_core_error.MastraError || (0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
 			throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "SAVE_THREAD", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,
@@ -12285,52 +12305,125 @@ var MemoryPG = class MemoryPG extends _mastra_core_storage.MemoryStorage {
 			}, error);
 		}
 	}
-	async updateThread({ id, title, metadata, fence }) {
+	#toThread(row) {
+		return {
+			id: row.id,
+			resourceId: row.resourceId,
+			title: row.title,
+			metadata: typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata,
+			createdAt: row.createdAtZ || row.createdAt,
+			updatedAt: row.updatedAtZ || row.updatedAt
+		};
+	}
+	async #lockThread(t, tableName, { id, resourceId }) {
+		const params = [id];
+		let query = `SELECT * FROM ${tableName} WHERE id = $1`;
+		if (resourceId !== void 0) {
+			query += ` AND "resourceId" = $2`;
+			params.push(resourceId);
+		}
+		const row = await t.oneOrNone(`${query} FOR UPDATE`, params);
+		return row ? this.#toThread(row) : null;
+	}
+	/**
+	* Writes `title` (when given) and the full `metadata` value (when given).
+	* Callers that merge metadata must hold the row lock from `#lockThread`.
+	*/
+	async #writeThread(q, tableName, { id, title, metadata }) {
+		const nowStr = toUtcISOString(/* @__PURE__ */ new Date());
+		const params = [
+			title ?? null,
+			nowStr,
+			nowStr,
+			id
+		];
+		let metadataSet = "";
+		if (metadata !== void 0) {
+			params.push(toPgJson(metadata));
+			metadataSet = "metadata = $5,";
+		}
+		const row = await q.oneOrNone(`UPDATE ${tableName}
+       SET
+         title = COALESCE($1, title),
+         ${metadataSet}
+         "updatedAt" = $2,
+         "updatedAtZ" = $3
+       WHERE id = $4
+       RETURNING *`, params);
+		return row ? this.#toThread(row) : null;
+	}
+	/**
+	* Cross-process atomic metadata read-modify-write: the thread row stays locked
+	* (`SELECT ... FOR UPDATE`) from the read through the write, so concurrent
+	* writers from any process serialize instead of overwriting each other.
+	*/
+	async updateThreadMetadata({ id, resourceId, update, fence: explicitFence }) {
+		const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence);
+		const threadsTable = getTableName$3({
+			indexName: _mastra_core_storage.TABLE_THREADS,
+			schemaName: getSchemaName$3(this.#schema)
+		});
+		try {
+			return await this.#db.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runFencesTable(), fence, "updateThreadMetadata");
+				const thread = await this.#lockThread(t, threadsTable, {
+					id,
+					resourceId
+				});
+				if (!thread) return null;
+				const metadata = update(thread);
+				if (!metadata) return thread;
+				return this.#writeThread(t, threadsTable, {
+					id,
+					metadata: mergeMetadata(thread.metadata, metadata)
+				});
+			});
+		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError || (0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("PG", "UPDATE_THREAD_METADATA", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { threadId: id }
+			}, error);
+		}
+	}
+	async updateThread({ id, title, metadata, fence: explicitFence }) {
 		const threadTableName = getTableName$3({
 			indexName: _mastra_core_storage.TABLE_THREADS,
 			schemaName: getSchemaName$3(this.#schema)
 		});
+		const notFound = () => new _mastra_core_error.MastraError({
+			id: (0, _mastra_core_storage.createStorageErrorId)("PG", "UPDATE_THREAD", "FAILED"),
+			domain: _mastra_core_error.ErrorDomain.STORAGE,
+			category: _mastra_core_error.ErrorCategory.USER,
+			text: `Thread ${id} not found`,
+			details: {
+				threadId: id,
+				title: title ?? null
+			}
+		});
 		try {
-			return await this.#fenced(fence, "updateThread", async (q) => {
-				const existingThread = await this.#getThreadById(q, { threadId: id });
-				if (!existingThread) throw new _mastra_core_error.MastraError({
-					id: (0, _mastra_core_storage.createStorageErrorId)("PG", "UPDATE_THREAD", "FAILED"),
-					domain: _mastra_core_error.ErrorDomain.STORAGE,
-					category: _mastra_core_error.ErrorCategory.USER,
-					text: `Thread ${id} not found`,
-					details: {
-						threadId: id,
-						title: title ?? null
-					}
+			if (metadata === void 0) return await this.#fenced(explicitFence, "updateThread", async (q) => {
+				const thread = await this.#writeThread(q, threadTableName, {
+					id,
+					title
 				});
-				const mergedMetadata = {
-					...existingThread.metadata,
-					...metadata
-				};
-				const nowStr = toUtcISOString(/* @__PURE__ */ new Date());
-				const thread = await q.one(`UPDATE ${threadTableName}
-                    SET
-                        title = COALESCE($1, title),
-                        metadata = $2,
-                        "updatedAt" = $3,
-                        "updatedAtZ" = $4
-                    WHERE id = $5
-                    RETURNING *
-                `, [
-					title ?? null,
-					mergedMetadata,
-					nowStr,
-					nowStr,
-					id
-				]);
-				return {
-					id: thread.id,
-					resourceId: thread.resourceId,
-					title: thread.title,
-					metadata: typeof thread.metadata === "string" ? JSON.parse(thread.metadata) : thread.metadata,
-					createdAt: thread.createdAtZ || thread.createdAt,
-					updatedAt: thread.updatedAtZ || thread.updatedAt
-				};
+				if (!thread) throw notFound();
+				return thread;
+			});
+			const fence = (0, _mastra_core_storage.resolveRunFence)(this, explicitFence);
+			return await this.#db.client.tx(async (t) => {
+				if (fence) await assertRunFence(t, this.#runFencesTable(), fence, "updateThread");
+				const existing = await this.#lockThread(t, threadTableName, { id });
+				if (!existing) throw notFound();
+				const thread = await this.#writeThread(t, threadTableName, {
+					id,
+					title,
+					metadata: mergeMetadata(existing.metadata, metadata)
+				});
+				if (!thread) throw notFound();
+				return thread;
 			});
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError || (0, _mastra_core_storage.isRunFenceConflictError)(error)) throw error;
@@ -17386,8 +17479,12 @@ ${onConflict}`,
 async function insertRows(client, schema, table, records, partitioning, onConflict) {
 	const insert = buildInsert(schema, table, records, onConflict);
 	if (!insert) return;
+	await withPartitionRetry(client, schema, table, records, partitioning, () => client.query(insert.text, insert.values));
+}
+/** Retry a complete write after creating a missing native partition, outside any failed transaction. */
+async function withPartitionRetry(client, schema, table, records, partitioning, write) {
 	try {
-		await client.query(insert.text, insert.values);
+		return await write();
 	} catch (error) {
 		if (!isMissingPartitionError(error) || await resolveMode(client, partitioning) !== "native") throw error;
 		const days = withinPartitionWindow(recordDays(records, SIGNAL_TIME_COLUMN[table]), partitioning);
@@ -17400,7 +17497,7 @@ async function insertRows(client, schema, table, records, partitioning, onConfli
 				cause
 			}), { cause });
 		});
-		await client.query(insert.text, insert.values);
+		return await write();
 	}
 }
 /** `42501`: the role may not create the child, or does not own the parent it must attach to. */
@@ -18334,13 +18431,47 @@ function pushFeedbackIdentity(acc, feedbackType, feedbackSource) {
 	acc.conditions.push(`"valueNumber" IS NOT NULL`);
 }
 async function createFeedback(client, schema, args, partitioning) {
-	const row = feedbackRecordToRow(args.feedback);
-	await insertRows(client, schema, TABLE_FEEDBACK_EVENTS, [row], partitioning, FEEDBACK_UPSERT_CLAUSE);
+	await writeFeedback(client, schema, [args.feedback], args.onConflict, partitioning);
+}
+async function replaceFeedback(client, schema, args, partitioning) {
+	await writeFeedback(client, schema, [args.feedback], "replace", partitioning, true);
 }
 async function batchCreateFeedback(client, schema, args, partitioning) {
-	if (args.feedbacks.length === 0) return;
-	const rows = [...new Map(args.feedbacks.map((feedback) => [feedback.feedbackId, feedback])).values()].map(feedbackRecordToRow);
-	await insertRows(client, schema, TABLE_FEEDBACK_EVENTS, rows, partitioning, FEEDBACK_UPSERT_CLAUSE);
+	await writeFeedback(client, schema, args.feedbacks, args.onConflict, partitioning);
+}
+/** Serialize feedback writes by ID, including absent IDs and retries with a different timestamp. */
+async function writeFeedback(client, schema, feedbacks, onConflict, partitioning, preserveIdentity = false) {
+	if (!feedbacks.length) return;
+	const currentFeedback = new Map((onConflict === "ignore" ? [...feedbacks].reverse() : feedbacks).map((feedback) => [feedback.feedbackId, feedback]));
+	const rows = [...currentFeedback.values()].map(feedbackRecordToRow);
+	const ids = [...currentFeedback.keys()].sort();
+	await withPartitionRetry(client, schema, TABLE_FEEDBACK_EVENTS, rows, partitioning, () => client.tx(async (tx) => {
+		await tx.query(`SELECT pg_advisory_xact_lock(hashtextextended(lock_key, 0))
+         FROM unnest($1::text[]) WITH ORDINALITY AS locks(lock_key, position)
+         ORDER BY position`, [ids.map((id) => JSON.stringify([
+			schema,
+			TABLE_FEEDBACK_EVENTS,
+			id
+		]))]);
+		const existing = await tx.any(`SELECT DISTINCT ON ("feedbackId") "feedbackId", "traceId", "timestamp", "organizationId", "resourceId"
+         FROM ${qualifiedTable(schema, TABLE_FEEDBACK_EVENTS)}
+         WHERE "feedbackId" = ANY($1::text[]) ORDER BY "feedbackId", "cursorId" DESC`, [ids]);
+		const byId = new Map(existing.map((row) => [row.feedbackId, row]));
+		const accepted = rows.filter((row) => {
+			const previous = byId.get(row.feedbackId);
+			if (!previous) return true;
+			if (onConflict === "ignore") return false;
+			if (preserveIdentity && (previous.traceId !== row.traceId || new Date(previous.timestamp).getTime() !== new Date(row.timestamp).getTime() || (previous.organizationId ?? null) !== (row.organizationId ?? null) || (previous.resourceId ?? null) !== (row.resourceId ?? null))) throw new _mastra_core_error.MastraError({
+				id: "OBSERVABILITY_FEEDBACK_IDENTITY_CONFLICT",
+				domain: _mastra_core_error.ErrorDomain.MASTRA_OBSERVABILITY,
+				category: _mastra_core_error.ErrorCategory.USER,
+				text: "Feedback replacement must preserve its trace, timestamp, and tenant"
+			});
+			return true;
+		});
+		const insert = buildInsert(schema, TABLE_FEEDBACK_EVENTS, accepted, FEEDBACK_UPSERT_CLAUSE);
+		if (insert) await tx.query(insert.text, insert.values);
+	}));
 }
 async function getFeedbackById(client, schema, feedbackId) {
 	const row = await client.oneOrNone(`SELECT ${FEEDBACK_SELECT_COLUMNS} FROM ${qualifiedTable(schema, TABLE_FEEDBACK_EVENTS)}
@@ -22031,6 +22162,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"thread-query",
 			"trace-query-tenant-scope",
 			"feedback",
+			"feedback-replacement",
 			"trace-query-context-ids",
 			...contextFieldFeatures,
 			...timingFeatures,
@@ -22059,6 +22191,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"thread-query",
 			"trace-query-tenant-scope",
 			"feedback",
+			"feedback-replacement",
 			"trace-query-context-ids",
 			...contextFieldFeatures,
 			...timingFeatures,
@@ -22158,6 +22291,9 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 	async batchCreateScores(args) {
 		await this.#run("BATCH_CREATE_SCORES", () => batchCreateScores(this.#client, this.#schema, args, this.#writePartitioning()), { count: args.scores.length });
 	}
+	async writeFeedbackReplacement(args) {
+		await this.#run("REPLACE_FEEDBACK", () => replaceFeedback(this.#client, this.#schema, args, this.#writePartitioning()));
+	}
 	async createFeedback(args) {
 		await this.#run("CREATE_FEEDBACK", () => createFeedback(this.#client, this.#schema, args, this.#writePartitioning()));
 	}
@@ -22183,7 +22319,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 		return this.#run("GET_SCORE_BY_ID", () => getScoreById(this.#readClient, this.#schema, scoreId), { scoreId });
 	}
 	async getFeedbackById(feedbackId) {
-		return this.#run("GET_FEEDBACK_BY_ID", () => getFeedbackById(this.#readClient, this.#schema, feedbackId), { feedbackId });
+		return this.#run("GET_FEEDBACK_BY_ID", () => getFeedbackById(this.#client, this.#schema, feedbackId), { feedbackId });
 	}
 	async listFeedback(args) {
 		return this.#run("LIST_FEEDBACK", () => listFeedback(this.#readClient, this.#schema, args));