@mastra/pg 1.22.0-alpha.0 → 1.22.0-alpha.4

package/dist/index.cjs

@@ -565,11 +565,22 @@ function buildFilterQuery(filter, minScore, topK) {
 }
 //#endregion
 //#region src/vector/index.ts
-const MAX_UPSERT_ROWS_PER_STATEMENT = Math.floor(65535 / 3);
+const DEFAULT_NAMESPACE = "default";
+const MAX_UPSERT_ROWS_PER_STATEMENT = Math.floor(65535 / 4);
 var PgVector = class extends _mastra_core_vector.MastraVector {
 	pool;
+	/**
+	* Cache for the public `getIndexInfo()`. Holds the in-flight promise rather than the
+	* resolved value so concurrent callers on a cold cache share a single round trip.
+	*/
 	describeIndexCache = /* @__PURE__ */ new Map();
+	/**
+	* Cache for the catalog-only index metadata used by the internal hot paths
+	* (cache warmup, query, upsert, updateVector, setupIndex). Also memoizes the promise.
+	*/
+	indexMetadataCache = /* @__PURE__ */ new Map();
 	createdIndexes = /* @__PURE__ */ new Map();
+	namespaceReadyIndexes = /* @__PURE__ */ new Set();
 	indexVectorTypes = /* @__PURE__ */ new Map();
 	mutexesByName = /* @__PURE__ */ new Map();
 	schema;
@@ -625,7 +636,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				try {
 					const existingIndexes = await this.listIndexes();
 					await Promise.all(existingIndexes.map(async (indexName) => {
-						const info = await this.getIndexInfo({ indexName });
+						const info = await this.getIndexMetadata({ indexName });
 						const key = await this.getIndexCacheKey({
 							indexName,
 							metric: info.metric,
@@ -798,20 +809,76 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 		const quotedVectorName = `"${parsedIndexName}_vector_idx"`;
 		return {
 			tableName: quotedSchemaName ? `${quotedSchemaName}.${quotedIndexName}` : quotedIndexName,
-			vectorIndexName: quotedVectorName
+			vectorIndexName: quotedVectorName,
+			parsedIndexName
 		};
 	}
 	getSchemaName() {
 		return this.schema ? `"${(0, _mastra_core_utils.parseSqlIdentifier)(this.schema, "schema name")}"` : void 0;
 	}
+	async ensureNamespaceSchema(indexName, client) {
+		const { tableName, parsedIndexName } = this.getTableName(indexName);
+		const schemaName = this.schema ? (0, _mastra_core_utils.parseSqlIdentifier)(this.schema, "schema name") : "public";
+		if ((await client.query(`SELECT 1
+       FROM information_schema.columns
+       WHERE table_schema = $1 AND table_name = $2 AND column_name = 'vector_id'`, [schemaName, parsedIndexName])).rowCount === 0) return;
+		await client.query(`ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS namespace VARCHAR(255) NOT NULL DEFAULT '${DEFAULT_NAMESPACE}'`);
+		const legacyConstraints = await client.query(`SELECT c.conname
+       FROM pg_constraint c
+       JOIN pg_class t ON t.oid = c.conrelid
+       JOIN pg_namespace n ON n.oid = t.relnamespace
+       WHERE n.nspname = $1
+         AND t.relname = $2
+         AND c.contype = 'u'
+         AND pg_get_constraintdef(c.oid) = 'UNIQUE (vector_id)'`, [schemaName, parsedIndexName]);
+		for (const { conname } of legacyConstraints.rows) {
+			const parsedConstraintName = (0, _mastra_core_utils.parseSqlIdentifier)(conname, "constraint name");
+			await client.query(`ALTER TABLE ${tableName} DROP CONSTRAINT "${parsedConstraintName}"`);
+		}
+		const namespaceIndexName = (0, _mastra_core_utils.parseSqlIdentifier)(`${parsedIndexName}_namespace_vector_id_idx`, "index name");
+		await client.query(`CREATE UNIQUE INDEX IF NOT EXISTS "${namespaceIndexName}" ON ${tableName} (namespace, vector_id)`);
+	}
 	transformFilter(filter) {
 		return new PGFilterTranslator().translate(filter);
 	}
+	/**
+	* Cached variant of {@link describeIndex}, including the row count.
+	*
+	* Internal code paths do not use this - they use the catalog-only
+	* {@link getIndexMetadata}, which never scans the table.
+	*/
 	async getIndexInfo({ indexName }) {
-		if (!this.describeIndexCache.has(indexName)) this.describeIndexCache.set(indexName, await this.describeIndex({ indexName }));
-		return this.describeIndexCache.get(indexName);
+		return this.memoize(this.describeIndexCache, indexName, () => this.describeIndex({ indexName }));
+	}
+	/**
+	* Cached index metadata read from the Postgres catalog only.
+	*
+	* This is what every internal caller needs: none of them read `count`, and paying for
+	* `SELECT COUNT(*)` on a large index costs a full heap scan per call.
+	*/
+	getIndexMetadata({ indexName }) {
+		return this.memoize(this.indexMetadataCache, indexName, () => this.describeIndexMetadata({ indexName }));
+	}
+	/**
+	* Stores the in-flight promise in `cache` so concurrent callers on a cold cache share one
+	* round trip, and drops the entry if it rejects so a transient failure is not cached forever.
+	*/
+	memoize(cache, key, load) {
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const pending = load();
+		cache.set(key, pending);
+		pending.catch(() => {
+			if (cache.get(key) === pending) cache.delete(key);
+		});
+		return pending;
+	}
+	/** Drops every cached view of an index, e.g. after its index definition or table changed. */
+	invalidateIndexCaches(indexName) {
+		this.describeIndexCache.delete(indexName);
+		this.indexMetadataCache.delete(indexName);
 	}
-	async query({ indexName, queryVector, topK = 10, filter, includeVector = false, minScore = -1, ef, probes }) {
+	async query({ indexName, queryVector, topK = 10, filter, includeVector = false, minScore = -1, ef, probes, namespace = DEFAULT_NAMESPACE }) {
 		try {
 			(0, _mastra_core_vector.validateTopK)("PG", topK);
 			if (queryVector !== void 0) {
@@ -832,16 +899,23 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			try {
 				const { sql: filterQuery, values: filterValues } = buildDeleteFilterQuery(this.transformFilter(filter));
 				const { tableName } = this.getTableName(indexName);
+				const filterClause = filterQuery.trim().replace(/^WHERE\s+/i, "");
+				const namespaceParam = filterValues.length + 1;
 				const query = `
           SELECT
             vector_id as id,
             metadata
             ${includeVector ? ", embedding" : ""}
           FROM ${tableName}
-          ${filterQuery}
+          WHERE namespace = $${namespaceParam}
+          ${filterClause ? `AND (${filterClause})` : ""}
           ORDER BY vector_id
-          LIMIT $${filterValues.length + 1}`;
-				return (await client.query(query, [...filterValues, topK])).rows.map(({ id, metadata, embedding }) => ({
+          LIMIT $${namespaceParam + 1}`;
+				return (await client.query(query, [
+					...filterValues,
+					namespace,
+					topK
+				])).rows.map(({ id, metadata, embedding }) => ({
 					id,
 					score: 0,
 					metadata,
@@ -865,7 +939,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			await this.ensureSearchPath(client);
 			await client.query("BEGIN");
 			const { sql: filterQuery, values: filterValues } = buildFilterQuery(this.transformFilter(filter), minScore, topK);
-			const indexInfo = await this.getIndexInfo({ indexName });
+			const indexInfo = await this.getIndexMetadata({ indexName });
 			const metric = indexInfo.metric ?? "cosine";
 			const ops = this.getVectorOps(indexInfo.vectorType, metric);
 			const vectorStr = ops.formatVector(queryVector, indexInfo.dimension);
@@ -873,14 +947,18 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				const calculatedEf = ef ?? Math.max(topK, (indexInfo?.config?.m ?? 16) * topK);
 				const searchEf = Math.min(1e3, Math.max(1, calculatedEf));
 				await client.query(`SET LOCAL hnsw.ef_search = ${searchEf}`);
+				await client.query(`SET LOCAL hnsw.iterative_scan = strict_order`);
 			}
 			if (indexInfo.type === "ivfflat" && probes) await client.query(`SET LOCAL ivfflat.probes = ${probes}`);
 			const { tableName } = this.getTableName(indexName);
 			const qualifiedVectorType = this.getVectorTypeName(indexInfo.vectorType, indexInfo.dimension);
 			const distanceExpr = `embedding ${ops.distanceOperator} '${vectorStr}'::${qualifiedVectorType}`;
 			const scoreExpr = ops.scoreExpr(distanceExpr);
-			const hasFilter = filterQuery.trim().length > 0;
-			const query = indexInfo.type === "hnsw" && !hasFilter && minScore <= 0 ? `
+			const filterClause = filterQuery.trim().replace(/^WHERE\s+/i, "");
+			const hasFilter = filterClause.length > 0;
+			const useIndexedOrder = indexInfo.type === "hnsw" && !hasFilter && minScore <= 0;
+			const namespaceParam = filterValues.length + 1;
+			const query = useIndexedOrder ? `
         WITH vector_scores AS (
           SELECT
             vector_id as id,
@@ -888,6 +966,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
             metadata
             ${includeVector ? ", embedding" : ""}
           FROM ${tableName}
+          WHERE namespace = $${namespaceParam}
           ORDER BY ${distanceExpr}
           LIMIT $2
         )
@@ -902,14 +981,15 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
             metadata
             ${includeVector ? ", embedding" : ""}
           FROM ${tableName}
-          ${filterQuery}
+          WHERE namespace = $${namespaceParam}
+          ${filterClause ? `AND (${filterClause})` : ""}
         )
         SELECT *
         FROM vector_scores
         WHERE score > $1
         ORDER BY score DESC
         LIMIT $2`;
-			const result = await client.query(query, filterValues);
+			const result = await client.query(query, [...filterValues, namespace]);
 			await client.query("COMMIT");
 			return result.rows.map(({ id, score, metadata, embedding }) => ({
 				id,
@@ -931,7 +1011,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			client.release();
 		}
 	}
-	async upsert({ indexName, vectors, metadata, ids, deleteFilter }) {
+	async upsert({ indexName, vectors, metadata, ids, deleteFilter, namespace = DEFAULT_NAMESPACE }) {
 		(0, _mastra_core_vector.validateUpsertInput)("PG", vectors, metadata, ids);
 		const { tableName } = this.getTableName(indexName);
 		const client = await this.pool.connect();
@@ -946,8 +1026,8 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				const { sql: filterQuery, values: filterValues } = buildDeleteFilterQuery(this.transformFilter(deleteFilter));
 				const whereClause = filterQuery.trim().replace(/^WHERE\s+/i, "");
 				if (whereClause) {
-					const deleteQuery = `DELETE FROM ${tableName} WHERE ${whereClause}`;
-					const result = await client.query(deleteQuery, filterValues);
+					const deleteQuery = `DELETE FROM ${tableName} WHERE namespace = $${filterValues.length + 1} AND (${whereClause})`;
+					const result = await client.query(deleteQuery, [...filterValues, namespace]);
 					this.logger?.debug(`Deleted ${result.rowCount || 0} vectors before upsert`, {
 						indexName,
 						deletedCount: result.rowCount || 0
@@ -955,15 +1035,15 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				}
 			}
 			const vectorIds = ids || vectors.map(() => crypto.randomUUID());
-			const indexInfo = await this.getIndexInfo({ indexName });
+			const indexInfo = await this.getIndexMetadata({ indexName });
 			const qualifiedVectorType = this.getVectorTypeName(indexInfo.vectorType, indexInfo.dimension);
 			const ops = this.getVectorOps(indexInfo.vectorType, indexInfo.metric ?? "cosine");
 			if (new Set(vectorIds).size !== vectorIds.length) for (let i = 0; i < vectors.length; i++) {
 				const vectorStr = ops.formatVector(vectors[i], indexInfo.dimension);
 				const query = `
-            INSERT INTO ${tableName} (vector_id, embedding, metadata)
-            VALUES ($1, $2::${qualifiedVectorType}, $3::jsonb)
-            ON CONFLICT (vector_id)
+            INSERT INTO ${tableName} (vector_id, embedding, metadata, namespace)
+            VALUES ($1, $2::${qualifiedVectorType}, $3::jsonb, $4)
+            ON CONFLICT (namespace, vector_id)
             DO UPDATE SET
               embedding = $2::${qualifiedVectorType},
               metadata = $3::jsonb
@@ -971,7 +1051,8 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				await client.query(query, [
 					vectorIds[i],
 					vectorStr,
-					JSON.stringify(metadata?.[i] || {})
+					JSON.stringify(metadata?.[i] || {}),
+					namespace
 				]);
 			}
 			else for (let start = 0; start < vectors.length; start += MAX_UPSERT_ROWS_PER_STATEMENT) {
@@ -980,13 +1061,13 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				const values = [];
 				for (let i = start; i < end; i++) {
 					const base = values.length;
-					rows.push(`($${base + 1}, $${base + 2}::${qualifiedVectorType}, $${base + 3}::jsonb)`);
-					values.push(vectorIds[i], ops.formatVector(vectors[i], indexInfo.dimension), JSON.stringify(metadata?.[i] || {}));
+					rows.push(`($${base + 1}, $${base + 2}::${qualifiedVectorType}, $${base + 3}::jsonb, $${base + 4})`);
+					values.push(vectorIds[i], ops.formatVector(vectors[i], indexInfo.dimension), JSON.stringify(metadata?.[i] || {}), namespace);
 				}
 				const query = `
-            INSERT INTO ${tableName} (vector_id, embedding, metadata)
+            INSERT INTO ${tableName} (vector_id, embedding, metadata, namespace)
             VALUES ${rows.join(", ")}
-            ON CONFLICT (vector_id)
+            ON CONFLICT (namespace, vector_id)
             DO UPDATE SET
               embedding = EXCLUDED.embedding,
               metadata = EXCLUDED.metadata
@@ -1106,9 +1187,9 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			vectorType,
 			metadataIndexes
 		});
-		if (this.cachedIndexExists(indexName, indexCacheKey)) return;
+		if (this.cachedIndexExists(indexName, indexCacheKey) && this.namespaceReadyIndexes.has(indexName)) return;
 		await this.getMutexByName(`create-${indexName}`).runExclusive(async () => {
-			if (this.cachedIndexExists(indexName, indexCacheKey)) return;
+			if (this.cachedIndexExists(indexName, indexCacheKey) && this.namespaceReadyIndexes.has(indexName)) return;
 			const client = await this.pool.connect();
 			try {
 				await this.setupSchema(client);
@@ -1152,12 +1233,15 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				await client.query(`
           CREATE TABLE IF NOT EXISTS ${tableName} (
             id SERIAL PRIMARY KEY,
-            vector_id TEXT UNIQUE NOT NULL,
+            vector_id TEXT NOT NULL,
             embedding ${qualifiedVectorType}(${dimension}),
-            metadata JSONB DEFAULT '{}'::jsonb
+            metadata JSONB DEFAULT '{}'::jsonb,
+            namespace VARCHAR(255) NOT NULL DEFAULT '${DEFAULT_NAMESPACE}'
           );
         `);
+				await this.ensureNamespaceSchema(indexName, client);
 				this.createdIndexes.set(indexName, indexCacheKey);
+				this.namespaceReadyIndexes.add(indexName);
 				this.indexVectorTypes.set(indexName, vectorType);
 				if (buildIndex) await this.setupIndex({
 					indexName,
@@ -1168,6 +1252,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				if (metadataIndexes?.length) await this.createMetadataIndexes(tableName, indexName, metadataIndexes);
 			} catch (error) {
 				this.createdIndexes.delete(indexName);
+				this.namespaceReadyIndexes.delete(indexName);
 				this.indexVectorTypes.delete(indexName);
 				throw error;
 			} finally {
@@ -1238,7 +1323,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			let existingIndexInfo = null;
 			let dimension = 0;
 			try {
-				existingIndexInfo = await this.getIndexInfo({ indexName });
+				existingIndexInfo = await this.getIndexMetadata({ indexName });
 				dimension = existingIndexInfo.dimension;
 				if (isConfigEmpty && existingIndexInfo.metric === metric) if (existingIndexInfo.type === "flat") this.logger?.debug(`No index exists for ${vectorIndexName}, will create default ivfflat index`);
 				else {
@@ -1273,12 +1358,12 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				}
 				this.logger?.info(`Index ${vectorIndexName} configuration changed, rebuilding index`);
 				await client.query(`DROP INDEX IF EXISTS ${vectorIndexName}`);
-				this.describeIndexCache.delete(indexName);
+				this.invalidateIndexCaches(indexName);
 			} catch {
 				this.logger?.debug(`Index ${indexName} doesn't exist yet, will create it`);
 			}
 			if (indexType === "flat") {
-				this.describeIndexCache.delete(indexName);
+				this.invalidateIndexCaches(indexName);
 				return;
 			}
 			await this.ensureSearchPath(client);
@@ -1428,6 +1513,19 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 	* @returns A promise that resolves to the index statistics including dimension, count and metric
 	*/
 	async describeIndex({ indexName }) {
+		const metadata = await this.describeIndexMetadata({ indexName });
+		const count = await this.countIndexRows({ indexName });
+		return {
+			...metadata,
+			count
+		};
+	}
+	/**
+	* Reads the index metadata that lives in the Postgres catalog. Unlike
+	* {@link describeIndex} it issues no `COUNT(*)`, so its cost does not grow with the
+	* number of rows in the table.
+	*/
+	async describeIndexMetadata({ indexName }) {
 		const client = await this.pool.connect();
 		try {
 			const { tableName } = this.getTableName(indexName);
@@ -1447,10 +1545,6 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
                 FROM pg_attribute
                 WHERE attrelid = $1::regclass
                 AND attname = 'embedding';
-            `;
-			const countQuery = `
-                SELECT COUNT(*) as count
-                FROM ${tableName};
             `;
 			const indexQuery = `
             SELECT
@@ -1466,7 +1560,6 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
             AND n.nspname = $2;
             `;
 			const dimResult = await client.query(dimensionQuery, [tableName]);
-			const countResult = await client.query(countQuery);
 			const { index_method, index_def, operator_class } = (await client.query(indexQuery, [`${indexName}_vector_idx`, this.schema || "public"])).rows[0] || {
 				index_method: "flat",
 				index_def: "",
@@ -1485,7 +1578,6 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			}
 			return {
 				dimension: dimResult.rows[0].dimension,
-				count: parseInt(countResult.rows[0].count),
 				metric,
 				type: index_method,
 				vectorType,
@@ -1505,14 +1597,41 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			client.release();
 		}
 	}
+	/**
+	* Exact row count for an index. This is a full scan of the table, so it is only issued
+	* for the public {@link describeIndex}, never from an internal code path.
+	*/
+	async countIndexRows({ indexName }) {
+		const client = await this.pool.connect();
+		try {
+			const { tableName } = this.getTableName(indexName);
+			const countResult = await client.query(`
+                SELECT COUNT(*) as count
+                FROM ${tableName};
+            `);
+			return parseInt(countResult.rows[0].count);
+		} catch (e) {
+			const mastraError = new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DESCRIBE_INDEX", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { indexName }
+			}, e);
+			this.logger?.trackException(mastraError);
+			throw mastraError;
+		} finally {
+			client.release();
+		}
+	}
 	async deleteIndex({ indexName }) {
 		const client = await this.pool.connect();
 		try {
 			const { tableName } = this.getTableName(indexName);
 			await client.query(`DROP TABLE IF EXISTS ${tableName} CASCADE`);
 			this.createdIndexes.delete(indexName);
+			this.namespaceReadyIndexes.delete(indexName);
 			this.indexVectorTypes.delete(indexName);
-			this.describeIndexCache.delete(indexName);
+			this.invalidateIndexCaches(indexName);
 		} catch (error) {
 			await client.query("ROLLBACK");
 			const mastraError = new _mastra_core_error.MastraError({
@@ -1562,7 +1681,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 	* @returns A promise that resolves when the update is complete.
 	* @throws Will throw an error if no updates are provided or if the update operation fails.
 	*/
-	async updateVector({ indexName, id, filter, update }) {
+	async updateVector({ indexName, id, filter, update, namespace = DEFAULT_NAMESPACE }) {
 		let client;
 		try {
 			if (!update.vector && !update.metadata) throw new Error("No updates provided");
@@ -1583,7 +1702,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			client = await this.pool.connect();
 			await this.ensureSearchPath(client);
 			const { tableName } = this.getTableName(indexName);
-			const indexInfo = await this.getIndexInfo({ indexName });
+			const indexInfo = await this.getIndexMetadata({ indexName });
 			const qualifiedVectorType = this.getVectorTypeName(indexInfo.vectorType, indexInfo.dimension);
 			const ops = this.getVectorOps(indexInfo.vectorType, indexInfo.metric ?? "cosine");
 			let updateParts = [];
@@ -1602,8 +1721,11 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 			if (updateParts.length === 0) return;
 			let whereClause;
 			let whereValues;
+			const namespaceIndex = valueIndex;
+			values.push(namespace);
+			valueIndex++;
 			if (id) {
-				whereClause = `vector_id = $${valueIndex}`;
+				whereClause = `namespace = $${namespaceIndex} AND vector_id = $${valueIndex}`;
 				whereValues = [id];
 			} else {
 				if (!filter || Object.keys(filter).length === 0) throw new _mastra_core_error.MastraError({
@@ -1628,6 +1750,7 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 				whereClause = whereClause.replace(/\$(\d+)/g, (match, num) => {
 					return `$${parseInt(num) + valueIndex - 1}`;
 				});
+				whereClause = `namespace = $${namespaceIndex} AND (${whereClause})`;
 				whereValues = filterValues;
 			}
 			const query = `
@@ -1667,16 +1790,16 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 	* @returns A promise that resolves when the deletion is complete.
 	* @throws Will throw an error if the deletion operation fails.
 	*/
-	async deleteVector({ indexName, id }) {
+	async deleteVector({ indexName, id, namespace = DEFAULT_NAMESPACE }) {
 		let client;
 		try {
 			client = await this.pool.connect();
 			const { tableName } = this.getTableName(indexName);
 			const query = `
         DELETE FROM ${tableName}
-        WHERE vector_id = $1
+        WHERE vector_id = $1 AND namespace = $2
       `;
-			await client.query(query, [id]);
+			await client.query(query, [id, namespace]);
 		} catch (error) {
 			const mastraError = new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DELETE_VECTOR", "FAILED"),
@@ -1700,14 +1823,15 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 	* @returns A promise that resolves when the deletion is complete.
 	* @throws Will throw an error if the deletion operation fails.
 	*/
-	async deleteVectors({ indexName, filter, ids }) {
+	async deleteVectors({ indexName, filter, ids, namespace }) {
 		let client;
+		const effectiveNamespace = namespace ?? DEFAULT_NAMESPACE;
 		try {
 			client = await this.pool.connect();
 			const { tableName } = this.getTableName(indexName);
-			if (!filter && !ids) throw new _mastra_core_error.MastraError({
+			if (!filter && !ids && namespace === void 0) throw new _mastra_core_error.MastraError({
 				id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DELETE_VECTORS", "NO_TARGET"),
-				text: "Either filter or ids must be provided",
+				text: "Either filter or ids must be provided, unless an explicit namespace is used",
 				domain: _mastra_core_error.ErrorDomain.MASTRA_VECTOR,
 				category: _mastra_core_error.ErrorCategory.USER,
 				details: { indexName }
@@ -1729,9 +1853,9 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 					category: _mastra_core_error.ErrorCategory.USER,
 					details: { indexName }
 				});
-				query = `DELETE FROM ${tableName} WHERE vector_id IN (${ids.map((_, i) => `$${i + 1}`).join(", ")})`;
-				values = ids;
-			} else {
+				query = `DELETE FROM ${tableName} WHERE vector_id IN (${ids.map((_, i) => `$${i + 1}`).join(", ")}) AND namespace = $${ids.length + 1}`;
+				values = [...ids, effectiveNamespace];
+			} else if (filter) {
 				if (!filter || Object.keys(filter).length === 0) throw new _mastra_core_error.MastraError({
 					id: (0, _mastra_core_storage.createVectorErrorId)("PG", "DELETE_VECTORS", "EMPTY_FILTER"),
 					text: "Cannot delete with empty filter. Use deleteIndex to delete all vectors.",
@@ -1751,8 +1875,11 @@ var PgVector = class extends _mastra_core_vector.MastraVector {
 						filter: JSON.stringify(filter)
 					}
 				});
-				query = `DELETE FROM ${tableName} WHERE ${whereClause}`;
-				values = filterValues;
+				query = `DELETE FROM ${tableName} WHERE namespace = $${filterValues.length + 1} AND (${whereClause})`;
+				values = [...filterValues, effectiveNamespace];
+			} else {
+				query = `DELETE FROM ${tableName} WHERE namespace = $1`;
+				values = [effectiveNamespace];
 			}
 			const result = await client.query(query, values);
 			this.logger?.info(`Deleted ${result.rowCount || 0} vectors from ${indexName}`, {
@@ -4918,7 +5045,7 @@ var BackgroundTasksPG = class BackgroundTasksPG extends _mastra_core_storage.Bac
 			}
 		});
 	}
-	async updateTask(taskId, update) {
+	async updateTask(taskId, update, options) {
 		const setClauses = [];
 		const params = [];
 		let paramIdx = 1;
@@ -4960,10 +5087,15 @@ var BackgroundTasksPG = class BackgroundTasksPG extends _mastra_core_storage.Bac
 			const val = update.completedAt?.toISOString() ?? null;
 			params.push(val, val);
 		}
-		if (setClauses.length === 0) return;
+		if (setClauses.length === 0) return false;
 		const table = getTableName$4(getSchemaName$4(this.#schema));
 		params.push(taskId);
-		await this.#db.client.none(`UPDATE ${table} SET ${setClauses.join(", ")} WHERE "id" = $${paramIdx}`, params);
+		let where = `"id" = $${paramIdx++}`;
+		if (options?.expectedStatus) {
+			where += ` AND "status" = $${paramIdx}`;
+			params.push(options.expectedStatus);
+		}
+		return ((await this.#db.client.query(`UPDATE ${table} SET ${setClauses.join(", ")} WHERE ${where}`, params)).rowCount ?? 0) > 0;
 	}
 	async getTask(taskId) {
 		const table = getTableName$4(getSchemaName$4(this.#schema));
@@ -6608,6 +6740,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				"tags",
 				"comment",
 				"toolMockReport",
+				"metadata",
 				"organizationId",
 				"projectId",
 				"attempt"
@@ -6804,6 +6937,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 			input: (0, _mastra_core_storage.safelyParseJSON)(row.input),
 			output: row.output ? (0, _mastra_core_storage.safelyParseJSON)(row.output) : null,
 			groundTruth: row.groundTruth ? (0, _mastra_core_storage.safelyParseJSON)(row.groundTruth) : null,
+			metadata: row.metadata ? (0, _mastra_core_storage.safelyParseJSON)(row.metadata) : null,
 			error: row.error ? (0, _mastra_core_storage.safelyParseJSON)(row.error) : null,
 			startedAt: (0, _mastra_core_storage.ensureDate)(row.startedAtZ || row.startedAt),
 			completedAt: (0, _mastra_core_storage.ensureDate)(row.completedAtZ || row.completedAt),
@@ -7112,6 +7246,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 					input: input.input,
 					output: input.output ?? null,
 					groundTruth: input.groundTruth ?? null,
+					metadata: input.metadata ?? null,
 					error: input.error ?? null,
 					startedAt: input.startedAt.toISOString(),
 					completedAt: input.completedAt.toISOString(),
@@ -7134,6 +7269,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				input: input.input,
 				output: input.output ?? null,
 				groundTruth: input.groundTruth ?? null,
+				metadata: input.metadata ?? null,
 				error: input.error ?? null,
 				startedAt: input.startedAt,
 				completedAt: input.completedAt,
@@ -7170,9 +7306,9 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 					const id = crypto.randomUUID();
 					return t.one(`INSERT INTO ${tableName} (
               "id", "experimentId", "itemId", "itemDatasetVersion", "organizationId", "projectId",
-              "input", "output", "groundTruth", "error", "startedAt", "completedAt",
+              "input", "output", "groundTruth", "metadata", "error", "startedAt", "completedAt",
               "retryCount", "attempt", "traceId", "status", "tags", "toolMockReport", "createdAt"
-            ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19)
+            ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20)
             RETURNING *`, [
 						id,
 						input.experimentId,
@@ -7183,6 +7319,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 						JSON.stringify(input.input),
 						input.output != null ? JSON.stringify(input.output) : null,
 						input.groundTruth != null ? JSON.stringify(input.groundTruth) : null,
+						input.metadata != null ? JSON.stringify(input.metadata) : null,
 						input.error != null ? JSON.stringify(input.error) : null,
 						input.startedAt.toISOString(),
 						input.completedAt.toISOString(),
@@ -7197,9 +7334,9 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 				}
 				return t.one(`UPDATE ${tableName} SET
             "itemDatasetVersion" = $2, "organizationId" = $3, "projectId" = $4,
-            "input" = $5, "output" = $6, "groundTruth" = $7, "error" = $8,
-            "startedAt" = $9, "completedAt" = $10, "retryCount" = $11, "attempt" = $12,
-            "traceId" = $13, "status" = $14, "tags" = $15, "toolMockReport" = $16
+            "input" = $5, "output" = $6, "groundTruth" = $7, "metadata" = $8, "error" = $9,
+            "startedAt" = $10, "completedAt" = $11, "retryCount" = $12, "attempt" = $13,
+            "traceId" = $14, "status" = $15, "tags" = $16, "toolMockReport" = $17
           WHERE "id" = $1 RETURNING *`, [
 					existing.id,
 					input.itemDatasetVersion ?? null,
@@ -7208,6 +7345,7 @@ var ExperimentsPG = class ExperimentsPG extends _mastra_core_storage.Experiments
 					JSON.stringify(input.input),
 					input.output != null ? JSON.stringify(input.output) : null,
 					input.groundTruth != null ? JSON.stringify(input.groundTruth) : null,
+					input.metadata != null ? JSON.stringify(input.metadata) : null,
 					input.error != null ? JSON.stringify(input.error) : null,
 					input.startedAt.toISOString(),
 					input.completedAt.toISOString(),
@@ -13591,6 +13729,11 @@ const SPAN_EVENT_COLUMNS = [
 		type: "boolean",
 		defaultSql: "false"
 	},
+	{
+		name: "isPending",
+		type: "boolean",
+		defaultSql: "false"
+	},
 	{
 		name: "startedAt",
 		type: "timestamptz"
@@ -13887,6 +14030,7 @@ const SPAN_LIGHT_SELECT_COLUMN_NAMES = [
 	"spanType",
 	"error",
 	"isEvent",
+	"isPending",
 	"startedAt",
 	"endedAt"
 ];
@@ -14281,6 +14425,26 @@ function allTableDDL(schema, mode) {
 		discoveryTableDDL(schema)
 	];
 }
+/**
+* Additive column migrations for tables created by an older version of this
+* schema. `CREATE TABLE IF NOT EXISTS` is a no-op on an existing table, so new
+* columns have to be added out of band.
+*
+* `ALTER TABLE` takes an AccessExclusiveLock on the partitioned parent, so
+* callers must check {@link columnExistsSQL} first and only run the statement
+* when the column is genuinely missing. On Postgres 11+ the non-volatile
+* default does not rewrite the table, and the ALTER cascades to partitions.
+*/
+function additiveColumns(schema) {
+	return [{
+		table: TABLE_SPAN_EVENTS,
+		column: "isPending",
+		ddl: `ALTER TABLE ${qualifiedTable(schema, TABLE_SPAN_EVENTS)} ADD COLUMN IF NOT EXISTS "isPending" boolean NOT NULL DEFAULT false`
+	}];
+}
+/** Existence probe for an additive column. Params: schema, table, column. */
+const columnExistsSQL = `SELECT 1 FROM information_schema.columns
+   WHERE table_schema = $1 AND table_name = $2 AND column_name = $3`;
 /** Index CREATEs. Safe to run repeatedly. */
 function allIndexDDL(schema) {
 	return tableIndexes().map((spec) => indexDDL(schema, spec));
@@ -14288,6 +14452,7 @@ function allIndexDDL(schema) {
 //#endregion
 //#region src/storage/domains/observability/v-next/discovery.ts
 const DEFAULT_TTL_SECONDS = 300;
+const DEFAULT_LOOKBACK_SECONDS = 720 * 60 * 60;
 /** All signal tables that contain a column. Used by cross-signal discovery. */
 const SIGNAL_TABLES_WITH_CONTEXT = [
 	TABLE_SPAN_EVENTS,
@@ -14352,22 +14517,71 @@ function startOrJoinRefresh(dedupeKey, cacheKey, refresh, upsert, logger) {
 async function readWithRefresh(client, schema, cacheKey, refresh, ttlSeconds, logger) {
 	const table = qualifiedTable(schema, TABLE_DISCOVERY);
 	const row = await client.oneOrNone(`SELECT "values", "refreshedAt" FROM ${table} WHERE "cacheKey" = $1`, [cacheKey]);
-	const refreshedAtMs = row ? new Date(row.refreshedAt).getTime() : 0;
-	if (!(!row || Date.now() - refreshedAtMs > ttlSeconds * 1e3)) return row.values;
-	const refreshing = startOrJoinRefresh(`${schema}:${cacheKey}`, cacheKey, refresh, (values) => upsertCache(client, schema, cacheKey, values), logger);
+	const dedupeKey = `${schema}:${cacheKey}`;
+	const startRefresh = () => startOrJoinRefresh(dedupeKey, cacheKey, refresh, (values) => upsertCache(client, schema, cacheKey, values), logger);
 	if (ttlSeconds <= 0) try {
-		return await refreshing;
+		return await startRefresh();
 	} catch {
 		return row?.values ?? [];
 	}
+	const refreshedAtMs = row ? new Date(row.refreshedAt).getTime() : 0;
+	if (!(!row || Date.now() - refreshedAtMs > ttlSeconds * 1e3)) return row.values;
 	if (!row) try {
-		return await refreshing;
+		return await startRefresh();
 	} catch {
 		return [];
 	}
-	refreshing.catch(() => {});
+	const previousRefreshedAt = row.refreshedAt;
+	claimRefresh(client, schema, cacheKey, ttlSeconds).then((claimedAt) => {
+		if (!claimedAt) return;
+		return startRefresh().then(() => {}, () => releaseClaim(client, schema, cacheKey, previousRefreshedAt, claimedAt));
+	}).catch(() => {});
 	return row.values;
 }
+/**
+* Try to become the process that refreshes `cacheKey`.
+*
+* The conditional UPDATE re-checks staleness in the database and stamps
+* `refreshedAt` in the same statement, so exactly one caller can transition a
+* given cache row out of the stale window — losers see zero rows updated and
+* skip their refresh. This is the cross-process counterpart to
+* `inFlightRefreshes`: N frontends going stale together run one refresh
+* instead of N.
+*
+* It reuses the cache table rather than an advisory lock because `DbClient`
+* is pool-backed, so a transaction-scoped lock would mean threading explicit
+* transaction handling through the discovery read path.
+*
+* The stamp is provisional in both directions: a completed refresh overwrites
+* it via `upsertCache`, and a failed one restores it via `releaseClaim`.
+*
+* Returns the exact provisional stamp written by the claim (or `null` when
+* the claim was lost) so `releaseClaim` can restore the row only while it
+* still holds this claim's stamp.
+*/
+async function claimRefresh(client, schema, cacheKey, ttlSeconds) {
+	const table = qualifiedTable(schema, TABLE_DISCOVERY);
+	return (await client.oneOrNone(`UPDATE ${table} SET "refreshedAt" = NOW()
+      WHERE "cacheKey" = $1 AND "refreshedAt" <= NOW() - ($2 || ' seconds')::interval
+     RETURNING "refreshedAt"::text AS "refreshedAt"`, [cacheKey, Math.floor(ttlSeconds)]))?.refreshedAt ?? null;
+}
+/**
+* Hand back a claim whose refresh failed by restoring the timestamp the
+* claiming reader observed. Guarded on the row still holding this claim's
+* exact provisional stamp so a refresh that completed in the meantime
+* (another process, or a later claim) isn't dragged backwards into staleness.
+*/
+async function releaseClaim(client, schema, cacheKey, previousRefreshedAt, claimedAt) {
+	const table = qualifiedTable(schema, TABLE_DISCOVERY);
+	try {
+		await client.query(`UPDATE ${table} SET "refreshedAt" = $2
+        WHERE "cacheKey" = $1 AND "refreshedAt" = $3::timestamptz`, [
+			cacheKey,
+			previousRefreshedAt,
+			claimedAt
+		]);
+	} catch {}
+}
 async function upsertCache(client, schema, cacheKey, values) {
 	const table = qualifiedTable(schema, TABLE_DISCOVERY);
 	await client.query(`INSERT INTO ${table} ("cacheKey", "refreshedAt", "values")
@@ -14376,61 +14590,95 @@ async function upsertCache(client, schema, cacheKey, values) {
        "refreshedAt" = EXCLUDED."refreshedAt",
        "values" = EXCLUDED."values"`, [cacheKey, JSON.stringify(values)]);
 }
-async function distinctAcrossTables(client, schema, column, tables, filterSql = "", filterParams = []) {
+/**
+* Time predicate that bounds a discovery refresh to recent events.
+*
+* Each signal table is range-partitioned on its own time column
+* (`SIGNAL_TIME_COLUMN`: `endedAt` for spans, `timestamp` for everything
+* else), so the predicate has to be built per table rather than shared across
+* a UNION. Bounding on that exact column is what lets the planner prune
+* partitions/chunks instead of scanning all history.
+*
+* The interval is interpolated rather than bound to a parameter on purpose:
+* the UNION branches in `distinctAcrossTables` and `getTags` all reference the
+* same positional placeholders, so adding a per-branch parameter would break
+* `$N` numbering. Safety comes from coercing to a finite integer here — the
+* value originates from `DiscoveryConfig`, never from user input.
+*/
+function lookbackPredicate(table, lookbackSeconds) {
+	if (!Number.isFinite(lookbackSeconds) || lookbackSeconds <= 0) return "";
+	const seconds = Math.floor(lookbackSeconds);
+	const timeColumn = SIGNAL_TIME_COLUMN[table];
+	if (!timeColumn) return "";
+	return `AND "${timeColumn}" >= NOW() - INTERVAL '${seconds} seconds'`;
+}
+async function distinctAcrossTables(client, schema, column, tables, lookbackSeconds, filterSql = "", filterParams = []) {
 	const safeColumn = (0, _mastra_core_utils.parseSqlIdentifier)(column, "column name");
-	const unions = tables.map((t) => `SELECT DISTINCT "${safeColumn}" AS v FROM ${qualifiedTable(schema, t)} WHERE "${safeColumn}" IS NOT NULL AND "${safeColumn}" <> '' ${filterSql}`).join(" UNION ");
+	const unions = tables.map((t) => `SELECT DISTINCT "${safeColumn}" AS v FROM ${qualifiedTable(schema, t)} WHERE "${safeColumn}" IS NOT NULL AND "${safeColumn}" <> '' ${filterSql} ${lookbackPredicate(t, lookbackSeconds)}`).join(" UNION ");
 	return (await client.manyOrNone(`SELECT v FROM (${unions}) sub ORDER BY v`, filterParams)).map((r) => r.v);
 }
 async function getEntityTypes(client, schema, _args, config) {
-	return { entityTypes: await readWithRefresh(client, schema, "entity_types", () => distinctAcrossTables(client, schema, "entityType", ENTITY_DISCOVERY_TABLES), config.ttlSeconds ?? DEFAULT_TTL_SECONDS, config.logger) };
+	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
+	return { entityTypes: await readWithRefresh(client, schema, "entity_types", () => distinctAcrossTables(client, schema, "entityType", ENTITY_DISCOVERY_TABLES, lookback), ttl, config.logger) };
 }
 async function getEntityNames(client, schema, args, config) {
 	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
 	const cacheKey = args.entityType ? `entity_names:${args.entityType}` : "entity_names";
 	const filterSql = args.entityType ? `AND "entityType" = $1` : "";
 	const filterParams = args.entityType ? [args.entityType] : [];
-	return { names: await readWithRefresh(client, schema, cacheKey, () => distinctAcrossTables(client, schema, "entityName", ENTITY_DISCOVERY_TABLES, filterSql, filterParams), ttl, config.logger) };
+	return { names: await readWithRefresh(client, schema, cacheKey, () => distinctAcrossTables(client, schema, "entityName", ENTITY_DISCOVERY_TABLES, lookback, filterSql, filterParams), ttl, config.logger) };
 }
 async function getServiceNames(client, schema, _args, config) {
-	return { serviceNames: await readWithRefresh(client, schema, "service_names", () => distinctAcrossTables(client, schema, "serviceName", SIGNAL_TABLES_WITH_CONTEXT), config.ttlSeconds ?? DEFAULT_TTL_SECONDS, config.logger) };
+	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
+	return { serviceNames: await readWithRefresh(client, schema, "service_names", () => distinctAcrossTables(client, schema, "serviceName", SIGNAL_TABLES_WITH_CONTEXT, lookback), ttl, config.logger) };
 }
 async function getEnvironments(client, schema, _args, config) {
-	return { environments: await readWithRefresh(client, schema, "environments", () => distinctAcrossTables(client, schema, "environment", SIGNAL_TABLES_WITH_CONTEXT), config.ttlSeconds ?? DEFAULT_TTL_SECONDS, config.logger) };
+	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
+	return { environments: await readWithRefresh(client, schema, "environments", () => distinctAcrossTables(client, schema, "environment", SIGNAL_TABLES_WITH_CONTEXT, lookback), ttl, config.logger) };
 }
 async function getTags(client, schema, args, config) {
 	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
 	const cacheKey = args.entityType ? `tags:${args.entityType}` : "tags";
 	const refresh = async () => {
 		const filter = args.entityType ? `AND "entityType" = $1` : "";
 		const params = args.entityType ? [args.entityType] : [];
-		const unions = ENTITY_DISCOVERY_TABLES.map((t) => `SELECT DISTINCT UNNEST("tags") AS v FROM ${qualifiedTable(schema, t)} WHERE array_length("tags", 1) > 0 ${filter}`).join(" UNION ");
+		const unions = ENTITY_DISCOVERY_TABLES.map((t) => `SELECT DISTINCT UNNEST("tags") AS v FROM ${qualifiedTable(schema, t)} WHERE array_length("tags", 1) > 0 ${filter} ${lookbackPredicate(t, lookback)}`).join(" UNION ");
 		return (await client.manyOrNone(`SELECT v FROM (${unions}) sub WHERE v IS NOT NULL AND v <> '' ORDER BY v`, params)).map((r) => r.v);
 	};
 	return { tags: await readWithRefresh(client, schema, cacheKey, refresh, ttl, config.logger) };
 }
 async function getMetricNames(client, schema, args, config) {
+	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
 	let filtered = await readWithRefresh(client, schema, "metric_names", async () => {
 		return (await client.manyOrNone(`SELECT DISTINCT "name" AS v FROM ${qualifiedTable(schema, TABLE_METRIC_EVENTS)}
-         WHERE "name" IS NOT NULL AND "name" <> '' ORDER BY "name"`)).map((r) => r.v);
-	}, config.ttlSeconds ?? DEFAULT_TTL_SECONDS, config.logger);
+         WHERE "name" IS NOT NULL AND "name" <> '' ${lookbackPredicate(TABLE_METRIC_EVENTS, lookback)} ORDER BY "name"`)).map((r) => r.v);
+	}, ttl, config.logger);
 	if (args.prefix) filtered = filtered.filter((v) => v.startsWith(args.prefix));
 	if (args.limit) filtered = filtered.slice(0, args.limit);
 	return { names: filtered };
 }
 async function getMetricLabelKeys(client, schema, args, config) {
 	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
 	return { keys: await readWithRefresh(client, schema, `metric_label_keys:${args.metricName}`, async () => {
 		return (await client.manyOrNone(`SELECT DISTINCT k AS v
          FROM ${qualifiedTable(schema, TABLE_METRIC_EVENTS)}, jsonb_object_keys("labels") k
-         WHERE "name" = $1 ORDER BY k`, [args.metricName])).map((r) => r.v);
+         WHERE "name" = $1 ${lookbackPredicate(TABLE_METRIC_EVENTS, lookback)} ORDER BY k`, [args.metricName])).map((r) => r.v);
 	}, ttl, config.logger) };
 }
 async function getMetricLabelValues(client, schema, args, config) {
 	const ttl = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+	const lookback = config.lookbackSeconds ?? DEFAULT_LOOKBACK_SECONDS;
 	let filtered = await readWithRefresh(client, schema, `metric_label_values:${args.metricName}:${args.labelKey}`, async () => {
 		return (await client.manyOrNone(`SELECT DISTINCT "labels" ->> $2 AS v
          FROM ${qualifiedTable(schema, TABLE_METRIC_EVENTS)}
-         WHERE "name" = $1 AND "labels" ? $2
+         WHERE "name" = $1 AND "labels" ? $2 ${lookbackPredicate(TABLE_METRIC_EVENTS, lookback)}
          ORDER BY v`, [args.metricName, args.labelKey])).map((r) => r.v).filter((v) => v != null && v !== "");
 	}, ttl, config.logger);
 	if (args.prefix) filtered = filtered.filter((v) => v.startsWith(args.prefix));
@@ -14669,6 +14917,7 @@ function commonContextToRow(record) {
 	};
 }
 function spanRecordToRow(span) {
+	const isPending = !span.isEvent && span.endedAt == null;
 	const endedAt = span.isEvent ? span.startedAt : span.endedAt ?? span.startedAt;
 	const metadata = span.metadata ?? null;
 	return {
@@ -14679,6 +14928,7 @@ function spanRecordToRow(span) {
 		name: span.name,
 		spanType: span.spanType,
 		isEvent: Boolean(span.isEvent),
+		isPending,
 		startedAt: toIsoOrDate(span.startedAt),
 		endedAt: toIsoOrDate(endedAt),
 		tags: normalizeTags(span.tags),
@@ -14693,9 +14943,19 @@ function spanRecordToRow(span) {
 		requestContext: jsonField(span.requestContext)
 	};
 }
+/**
+* Recover a span's real `endedAt` from its row. A pending row carries a
+* synthesized `endedAt` (a copy of `startedAt`) because the column is part of
+* the primary key; callers must see null so the span reads as still running.
+*/
+function spanRowEndedAt(row, startedAt) {
+	if (row.isEvent) return startedAt;
+	if (row.isPending) return null;
+	return toDateOrNull(row.endedAt);
+}
 function rowToSpanRecord(row) {
 	const startedAt = toDate(row.startedAt);
-	const endedAt = row.isEvent ? startedAt : toDateOrNull(row.endedAt);
+	const endedAt = spanRowEndedAt(row, startedAt);
 	const error = parsedJson(row.error);
 	const { executionSource, ...ctx } = rowToCommonContext(row);
 	return {
@@ -14729,7 +14989,7 @@ function rowToSpanRecord(row) {
 */
 function rowToLightSpanRecord(row) {
 	const startedAt = toDate(row.startedAt);
-	const endedAt = row.isEvent ? startedAt : toDateOrNull(row.endedAt);
+	const endedAt = spanRowEndedAt(row, startedAt);
 	return {
 		traceId: row.traceId,
 		spanId: row.spanId,
@@ -15260,22 +15520,42 @@ const COMPLEX_GROUP_BY_EXCLUDED = /* @__PURE__ */ new Set([
 	"requestContext"
 ]);
 //#endregion
+//#region src/storage/db/sanitize-json.ts
+/**
+* Sanitizes JSON string for PostgreSQL jsonb:
+* - Removes problematic Unicode sequences:
+*   - \u0000 (null character) - causes error 22P05 "unsupported Unicode escape sequence"
+*   - \uD800-\uDFFF (unpaired surrogates) - causes "Unicode low surrogate must follow a high surrogate"
+*   - \\uD800 (escaped-backslash + surrogate, e.g. from JS regex literals like [^\ud800-\udfff]):
+*     removing just \uXXXX would leave a dangling backslash that creates a new invalid escape (e.g. \-)
+* - Escapes any remaining invalid JSON escape sequences (e.g. \v, \k, \-)
+*/
+function sanitizeJsonForPg(jsonString) {
+	return jsonString.replace(/\\\\?u(0000|[Dd][89A-Fa-f][0-9A-Fa-f]{2})/g, "").replace(/(^|[^\\])(\\(?!["\\/bfnrtu]))/g, "$1\\\\");
+}
+//#endregion
 //#region src/storage/domains/observability/v-next/sql.ts
 /**
 * SQL helpers for the v-next Postgres observability domain.
 *
-* Provides a multi-row INSERT builder with `ON CONFLICT DO NOTHING` for
-* insert-only retry idempotency, and explicit jsonb / text[] casts so the
-* pg driver doesn't have to guess column types.
+* Provides a multi-row INSERT builder with a configurable conflict clause
+* (`ON CONFLICT DO NOTHING` by default, for retry idempotency), and explicit
+* jsonb / text[] casts so the pg driver doesn't have to guess column types.
 */
 /**
 * Encode a JS value for a `$N::jsonb` cast. Always `JSON.stringify` so a
 * plain string like `"hello"` becomes `"hello"` (a valid JSON scalar) and
 * not the bare word `hello`, which Postgres rejects when cast to jsonb.
+*
+* The result is sanitized because Postgres rejects some sequences that are
+* legal in JSON: NUL (`\u0000`) fails with 22P05 and unpaired UTF-16
+* surrogates fail with 22P02. Inserts here are batched into a single
+* multi-row statement, so one bad value would otherwise reject the whole
+* batch of observability events.
 */
 function encodeJsonb(value) {
 	if (value === null || value === void 0) return null;
-	return JSON.stringify(value);
+	return sanitizeJsonForPg(JSON.stringify(value));
 }
 /**
 * Build a multi-row INSERT with explicit column types and ON CONFLICT DO NOTHING.
@@ -15286,7 +15566,7 @@ function encodeJsonb(value) {
 *                   All records must have identical key sets.
 * @returns          { text, values } ready to pass to `client.query`.
 */
-function buildInsert(schema, table, records) {
+function buildInsert(schema, table, records, onConflict = "ON CONFLICT DO NOTHING") {
 	if (records.length === 0) return null;
 	const columns = Object.keys(records[0]).map((c) => (0, _mastra_core_utils.parseSqlIdentifier)(c, "column name"));
 	const quotedColumns = columns.map((c) => `"${c}"`).join(", ");
@@ -15312,10 +15592,44 @@ function buildInsert(schema, table, records) {
 	return {
 		text: `INSERT INTO ${qualifiedTable(schema, table)} (${quotedColumns})
 VALUES ${rowPlaceholders.join(", ")}
-ON CONFLICT DO NOTHING`,
+${onConflict}`,
 		values
 	};
 }
+/** Primary key of the span table; also the conflict target for span upserts. */
+const SPAN_KEY_COLUMNS = [
+	"traceId",
+	"spanId",
+	"endedAt"
+];
+/**
+* Conflict clause for span writes.
+*
+* A span is written twice under the event-sourced strategy: once when it starts
+* (`isPending = true`, `endedAt` synthesized from `startedAt`) and once when it
+* ends. Those two rows normally differ in `endedAt` and so coexist under the
+* primary key. A zero-duration span is the exception — its real `endedAt`
+* equals its `startedAt`, so the end row collides with the pending row. Letting
+* `DO NOTHING` win there would strand the span as permanently running, so the
+* end row overwrites the pending one instead.
+*
+* The `WHERE` guard keeps the clause a no-op for every other conflict, which
+* preserves insert-only retry idempotency: a replayed end row cannot clobber
+* the row it duplicates, and a late-arriving start row cannot revert an ended
+* span to pending.
+*/
+function spanConflictClause(columns) {
+	return `ON CONFLICT ("traceId", "spanId", "endedAt") DO UPDATE SET ${columns.filter((column) => !SPAN_KEY_COLUMNS.includes(column)).map((column) => `"${column}" = EXCLUDED."${column}"`).join(", ")}
+WHERE ${TABLE_SPAN_EVENTS}."isPending" AND NOT EXCLUDED."isPending"`;
+}
+/**
+* Ordering that picks the winning row for a span under the event-sourced write
+* model. An ended row always beats a pending row for the same span; among rows
+* of the same kind the latest write wins, with `cursorId` breaking ties between
+* rows that share a timestamp. Combine with `DISTINCT ON` (or `LIMIT 1`) after
+* the grouping key to collapse a span's rows down to one.
+*/
+const SPAN_COLLAPSE_ORDER = "\"isPending\" ASC, \"endedAt\" DESC, \"cursorId\" DESC";
 /**
 * Standard SELECT column list for tracing tables. The select projects every
 * column the row→record converters expect.
@@ -16311,12 +16625,51 @@ async function getScorePercentiles(client, schema, args) {
 function asIsoTimestamp(value) {
 	return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
 }
+/**
+* Ordering that picks the row representing a trace's current root.
+*
+* A trace can hold more than one root row. A span is written once when it
+* starts and again when it ends, and a durable run that suspends ends its root
+* span and opens a fresh one on resume. In both cases the newest row is the one
+* that describes the trace right now, and `cursorId` — a sequence assigned at
+* insert — is what "newest" means here. It also orders correctly where
+* timestamps cannot: a zero-duration span has `startedAt = endedAt`, and a
+* resumed root starts after the suspended root ended.
+*/
+const ROOT_COLLAPSE_ORDER = "\"cursorId\" DESC";
+/**
+* Predicate that keeps only the winning row for each span — the ended row when
+* one exists, the newest row otherwise. Mirrors `SPAN_COLLAPSE_ORDER` as an
+* anti-join, for the same reason as {@link latestRootPredicate}.
+*/
+function latestSpanPredicate(spanTable) {
+	return `NOT EXISTS (
+    SELECT 1 FROM ${spanTable} newer
+    WHERE newer."traceId" = r."traceId"
+      AND newer."spanId" = r."spanId"
+      AND (newer."isPending" < r."isPending" OR (newer."isPending" = r."isPending" AND newer."cursorId" > r."cursorId"))
+  )`;
+}
+/**
+* Predicate that keeps only a trace's current root row, as an anti-join rather
+* than a `DISTINCT ON`. Written this way so the outer query still scans the
+* partial root indexes and streams rows in `LIMIT`-order; grouping first would
+* force every root in the table to be read before the first page came back.
+*/
+function latestRootPredicate(spanTable) {
+	return `NOT EXISTS (
+    SELECT 1 FROM ${spanTable} newer
+    WHERE newer."traceId" = r."traceId"
+      AND newer."parentSpanId" IS NULL
+      AND newer."cursorId" > r."cursorId"
+  )`;
+}
 async function getRootSpan(client, schema, args) {
 	const table = qualifiedTable(schema, TABLE_SPAN_EVENTS);
 	const row = await client.oneOrNone(`SELECT ${SPAN_SELECT_COLUMNS}
      FROM ${table}
      WHERE "traceId" = $1 AND "parentSpanId" IS NULL
-     ORDER BY "endedAt" DESC
+     ORDER BY ${ROOT_COLLAPSE_ORDER}
      LIMIT 1`, [args.traceId]);
 	if (!row) return null;
 	return { span: rowToSpanRecord(row) };
@@ -16328,7 +16681,7 @@ async function getRootSpan(client, schema, args) {
 * planner. Starts numbering from `nextParamIdx`.
 */
 function buildListTracesFilters(filters, spanTable, nextParamIdx) {
-	const conditions = [`r."parentSpanId" IS NULL`];
+	const conditions = [`r."parentSpanId" IS NULL`, latestRootPredicate(spanTable)];
 	const params = [];
 	let i = nextParamIdx;
 	if (!filters) return {
@@ -16345,11 +16698,11 @@ function buildListTracesFilters(filters, spanTable, nextParamIdx) {
 		params.push(asIsoTimestamp(filters.startedAt.end));
 	}
 	if (filters.endedAt?.start) {
-		conditions.push(`r."endedAt" ${filters.endedAt.startExclusive ? ">" : ">="} $${i++}`);
+		conditions.push(`(NOT r."isPending" AND r."endedAt" ${filters.endedAt.startExclusive ? ">" : ">="} $${i++})`);
 		params.push(asIsoTimestamp(filters.endedAt.start));
 	}
 	if (filters.endedAt?.end) {
-		conditions.push(`r."endedAt" ${filters.endedAt.endExclusive ? "<" : "<="} $${i++}`);
+		conditions.push(`(NOT r."isPending" AND r."endedAt" ${filters.endedAt.endExclusive ? "<" : "<="} $${i++})`);
 		params.push(asIsoTimestamp(filters.endedAt.end));
 	}
 	if (filters.spanType !== void 0) {
@@ -16421,10 +16774,10 @@ function buildListTracesFilters(filters, spanTable, nextParamIdx) {
 			conditions.push(`r."error" IS NOT NULL`);
 			break;
 		case _mastra_core_storage.TraceStatus.RUNNING:
-			conditions.push(`FALSE`);
+			conditions.push(`r."isPending"`);
 			break;
 		case _mastra_core_storage.TraceStatus.SUCCESS:
-			conditions.push(`r."error" IS NULL`);
+			conditions.push(`r."error" IS NULL AND NOT r."isPending"`);
 			break;
 	}
 	if (filters.hasChildError !== void 0) {
@@ -16561,8 +16914,8 @@ function buildBranchSpanTypeClause(userSpanType, params, startIdx) {
 * NOT have a `parentSpanId IS NULL` predicate — branches can be nested under
 * other spans. Returns the bound params and the next param index.
 */
-function buildListBranchesFilters(filters, spanType, nextParamIdx) {
-	const conditions = [];
+function buildListBranchesFilters(filters, spanType, spanTable, nextParamIdx) {
+	const conditions = [latestSpanPredicate(spanTable)];
 	const params = [];
 	let i = nextParamIdx;
 	const spanTypeClause = buildBranchSpanTypeClause(spanType, params, i);
@@ -16583,11 +16936,11 @@ function buildListBranchesFilters(filters, spanType, nextParamIdx) {
 		params.push(asIsoTimestamp(filters.startedAt.end));
 	}
 	if (filters.endedAt?.start) {
-		conditions.push(`r."endedAt" ${filters.endedAt.startExclusive ? ">" : ">="} $${i++}`);
+		conditions.push(`(NOT r."isPending" AND r."endedAt" ${filters.endedAt.startExclusive ? ">" : ">="} $${i++})`);
 		params.push(asIsoTimestamp(filters.endedAt.start));
 	}
 	if (filters.endedAt?.end) {
-		conditions.push(`r."endedAt" ${filters.endedAt.endExclusive ? "<" : "<="} $${i++}`);
+		conditions.push(`(NOT r."isPending" AND r."endedAt" ${filters.endedAt.endExclusive ? "<" : "<="} $${i++})`);
 		params.push(asIsoTimestamp(filters.endedAt.end));
 	}
 	if (filters.traceId !== void 0) {
@@ -16699,10 +17052,10 @@ function buildListBranchesFilters(filters, spanType, nextParamIdx) {
 			conditions.push(`r."error" IS NOT NULL`);
 			break;
 		case _mastra_core_storage.TraceStatus.RUNNING:
-			conditions.push(`FALSE`);
+			conditions.push(`r."isPending"`);
 			break;
 		case _mastra_core_storage.TraceStatus.SUCCESS:
-			conditions.push(`r."error" IS NULL`);
+			conditions.push(`r."error" IS NULL AND NOT r."isPending"`);
 			break;
 	}
 	return {
@@ -16721,7 +17074,7 @@ async function listBranches(client, schema, args) {
 	return listBranchesPage(client, span, filters, pagination.page, pagination.perPage, orderBy.field, orderBy.direction);
 }
 async function listBranchesPage(client, span, filters, page, perPage, orderField, orderDir) {
-	const built = buildListBranchesFilters(filters, filters?.spanType, 1);
+	const built = buildListBranchesFilters(filters, filters?.spanType, span, 1);
 	if (!built) {
 		const deltaCursor = deltaPollingFeatureEnabled() ? await readBranchesStreamHeadCursor(client, span, filters) : void 0;
 		return {
@@ -16775,7 +17128,7 @@ async function listBranchesDelta(client, span, filters, after, limit) {
 			deltaCursor
 		};
 	}
-	const built = buildListBranchesFilters(filters, filters?.spanType, 1);
+	const built = buildListBranchesFilters(filters, filters?.spanType, span, 1);
 	if (!built) return {
 		branches: [],
 		delta: {
@@ -16818,14 +17171,35 @@ async function readBranchesStreamHeadCursor(client, span, filters) {
 }
 //#endregion
 //#region src/storage/domains/observability/v-next/tracing.ts
-async function createSpan(client, schema, args) {
-	const insert = buildInsert(schema, TABLE_SPAN_EVENTS, [spanRecordToRow(args.span)]);
+async function writeSpanRows(client, schema, rows) {
+	const deduped = dedupeSpanRows(rows);
+	const insert = buildInsert(schema, TABLE_SPAN_EVENTS, deduped, spanConflictClause(Object.keys(deduped[0] ?? {})));
 	if (insert) await client.query(insert.text, insert.values);
 }
+/**
+* Collapse rows that share a primary key within a single batch. Postgres
+* rejects an `ON CONFLICT DO UPDATE` statement whose VALUES list would touch
+* the same row twice, which a batch containing both the start and the end of a
+* zero-duration span would do. The ended row wins, matching what the conflict
+* clause would have done across two separate statements.
+*/
+function dedupeSpanRows(rows) {
+	if (rows.length < 2) return rows;
+	const byKey = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const key = `${row.traceId}\u0000${row.spanId}\u0000${String(row.endedAt)}`;
+		const existing = byKey.get(key);
+		if (existing && !existing.isPending) continue;
+		byKey.set(key, row);
+	}
+	return [...byKey.values()];
+}
+async function createSpan(client, schema, args) {
+	await writeSpanRows(client, schema, [spanRecordToRow(args.span)]);
+}
 async function batchCreateSpans(client, schema, args) {
 	if (args.records.length === 0) return;
-	const insert = buildInsert(schema, TABLE_SPAN_EVENTS, args.records.map(spanRecordToRow));
-	if (insert) await client.query(insert.text, insert.values);
+	await writeSpanRows(client, schema, args.records.map(spanRecordToRow));
 }
 async function getSpans(client, schema, args) {
 	if (args.spanIds.length === 0) return {
@@ -16833,10 +17207,13 @@ async function getSpans(client, schema, args) {
 		spans: []
 	};
 	const table = qualifiedTable(schema, TABLE_SPAN_EVENTS);
-	const rows = await client.manyOrNone(`SELECT ${SPAN_SELECT_COLUMNS}
-     FROM ${table}
-     WHERE "traceId" = $1
-       AND "spanId" = ANY($2::text[])
+	const rows = await client.manyOrNone(`SELECT * FROM (
+       SELECT DISTINCT ON ("spanId") ${SPAN_SELECT_COLUMNS}
+       FROM ${table}
+       WHERE "traceId" = $1
+         AND "spanId" = ANY($2::text[])
+       ORDER BY "spanId", ${SPAN_COLLAPSE_ORDER}
+     ) collapsed
      ORDER BY "startedAt" ASC`, [args.traceId, args.spanIds]);
 	return {
 		traceId: args.traceId,
@@ -16848,16 +17225,19 @@ async function getSpan(client, schema, args) {
 	const row = await client.oneOrNone(`SELECT ${SPAN_SELECT_COLUMNS}
      FROM ${table}
      WHERE "traceId" = $1 AND "spanId" = $2
-     ORDER BY "endedAt" DESC
+     ORDER BY ${SPAN_COLLAPSE_ORDER}
      LIMIT 1`, [args.traceId, args.spanId]);
 	if (!row) return null;
 	return { span: rowToSpanRecord(row) };
 }
 async function getTrace(client, schema, args) {
 	const table = qualifiedTable(schema, TABLE_SPAN_EVENTS);
-	const rows = await client.manyOrNone(`SELECT ${SPAN_SELECT_COLUMNS}
-     FROM ${table}
-     WHERE "traceId" = $1
+	const rows = await client.manyOrNone(`SELECT * FROM (
+       SELECT DISTINCT ON ("spanId") ${SPAN_SELECT_COLUMNS}
+       FROM ${table}
+       WHERE "traceId" = $1
+       ORDER BY "spanId", ${SPAN_COLLAPSE_ORDER}
+     ) collapsed
      ORDER BY "startedAt" ASC`, [args.traceId]);
 	if (!rows.length) return null;
 	return {
@@ -16867,9 +17247,12 @@ async function getTrace(client, schema, args) {
 }
 async function getTraceLight(client, schema, args) {
 	const table = qualifiedTable(schema, TABLE_SPAN_EVENTS);
-	const rows = await client.manyOrNone(`SELECT ${SPAN_LIGHT_SELECT_COLUMNS}
-     FROM ${table}
-     WHERE "traceId" = $1
+	const rows = await client.manyOrNone(`SELECT * FROM (
+       SELECT DISTINCT ON ("spanId") ${SPAN_LIGHT_SELECT_COLUMNS}
+       FROM ${table}
+       WHERE "traceId" = $1
+       ORDER BY "spanId", ${SPAN_COLLAPSE_ORDER}
+     ) collapsed
      ORDER BY "startedAt" ASC`, [args.traceId]);
 	if (!rows.length) return null;
 	return {
@@ -16980,6 +17363,11 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			} catch (error) {
 				if (!isDuplicateRelationError(error)) throw error;
 			}
+			for (const { table, column, ddl } of additiveColumns(this.#schema)) if (!await this.#client.oneOrNone(columnExistsSQL, [
+				this.#schema,
+				table,
+				column
+			])) await this.#client.none(ddl);
 			for (const ddl of allIndexDDL(this.#schema)) try {
 				await this.#client.none(ddl);
 			} catch (error) {
@@ -17076,8 +17464,8 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 	}
 	get observabilityStrategy() {
 		return {
-			preferred: "insert-only",
-			supported: ["insert-only"]
+			preferred: "event-sourced",
+			supported: ["event-sourced"]
 		};
 	}
 	getFeatures() {
@@ -20501,18 +20889,6 @@ function workflowSnapshotStatusIndexSQL(indexName, schemaName) {
 		schemaName: getSchemaName(schemaName)
 	})} (workflow_name, (snapshot ->> 'status'), "createdAt" DESC)`;
 }
-/**
-* Sanitizes JSON string for PostgreSQL jsonb:
-* - Removes problematic Unicode sequences:
-*   - \u0000 (null character) - causes error 22P05 "unsupported Unicode escape sequence"
-*   - \uD800-\uDFFF (unpaired surrogates) - causes "Unicode low surrogate must follow a high surrogate"
-*   - \\uD800 (escaped-backslash + surrogate, e.g. from JS regex literals like [^\ud800-\udfff]):
-*     removing just \uXXXX would leave a dangling backslash that creates a new invalid escape (e.g. \-)
-* - Escapes any remaining invalid JSON escape sequences (e.g. \v, \k, \-)
-*/
-function sanitizeJsonForPg(jsonString) {
-	return jsonString.replace(/\\\\?u(0000|[Dd][89A-Fa-f][0-9A-Fa-f]{2})/g, "").replace(/(^|[^\\])(\\(?!["\\/bfnrtu]))/g, "$1\\\\");
-}
 var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorage {
 	#db;
 	#schema;
@@ -20792,11 +21168,11 @@ var WorkflowsPG = class WorkflowsPG extends _mastra_core_storage.WorkflowsStorag
 			await this.#db.client.none(`INSERT INTO ${getTableName({
 				indexName: _mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT,
 				schemaName: getSchemaName(this.#schema)
-			})}
+			})} AS t
                  (workflow_name, run_id, "resourceId", snapshot, "createdAt", "updatedAt", "createdAtZ", "updatedAtZ")
                  VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
                  ON CONFLICT (workflow_name, run_id) DO UPDATE
-                 SET "resourceId" = $3, snapshot = $4, "updatedAt" = $6, "updatedAtZ" = $8`, [
+                 SET "resourceId" = COALESCE($3, t."resourceId"), snapshot = $4, "updatedAt" = $6, "updatedAtZ" = $8`, [
 				workflowName,
 				runId,
 				resourceId,
@@ -21650,7 +22026,7 @@ var PgFactoryStorageOps = class {
 					row[name] = Boolean(value);
 					break;
 				case "json":
-					row[name] = typeof value === "string" ? JSON.parse(value) : value;
+					row[name] = value;
 					break;
 				case "bigint":
 				case "integer":
@@ -21754,6 +22130,12 @@ var PgFactoryStorageOps = class {
 	async findMany(collection, where, opts) {
 		return this.#select(this.#queryable, collection, where, opts);
 	}
+	async count(collection, where) {
+		const schema = this.#schema(collection);
+		const filter = this.#buildWhere(schema, where);
+		const result = await this.#queryable.query(`SELECT COUNT(*) AS count FROM "${schema.name}" WHERE ${filter.sql}`, filter.args);
+		return Number(result.rows[0]?.count ?? 0);
+	}
 	async insertOne(collection, row) {
 		const schema = this.#schema(collection);
 		const pk = primaryKeyOf(schema);