@mastra/pg 1.32.0-alpha.2 → 1.32.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.32.0-alpha.2"
+  version: "1.32.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.32.0-alpha.2",
+  "version": "1.32.0-alpha.3",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -19209,6 +19209,9 @@ async function getScorePercentiles(client, schema, args) {
 //#endregion
 //#region src/storage/domains/observability/v-next/trace-query.ts
 const TRACE_STATUS_SQL = `CASE WHEN r."error" IS NOT NULL THEN 'error' ELSE 'success' END`;
+/** Core versions without the field reject it in strict query results, so it is only returned when core knows it. */
+const timeToFirstChunkSupported = "timeToFirstChunkMs" in _mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY.trace;
+const timeToFirstChunkFeatures = timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [];
 function durationMsSql(startedAt, endedAt) {
 	return `EXTRACT(EPOCH FROM (${endedAt} - ${startedAt}))::numeric * 1000`;
 }
@@ -19223,8 +19226,11 @@ const TRACE_FIELDS = {
 	startedAt: "r.\"startedAt\"",
 	endedAt: "r.\"endedAt\"",
 	durationMs: durationMsSql("r.\"startedAt\"", "r.\"endedAt\""),
+	timeToFirstChunkMs: "r.\"timeToFirstChunkMs\"",
 	entityName: "r.\"entityName\"",
 	entityType: "r.\"entityType\"",
+	name: "r.\"name\"",
+	spanType: "r.\"spanType\"",
 	environment: "r.\"environment\"",
 	status: TRACE_STATUS_SQL,
 	tags: "r.\"tags\""
@@ -19237,6 +19243,7 @@ const SPAN_FIELDS = {
 	startedAt: "s.\"startedAt\"",
 	endedAt: "s.\"endedAt\"",
 	durationMs: "s.\"durationMs\"",
+	timeToFirstChunkMs: "s.\"timeToFirstChunkMs\"",
 	status: "s.\"status\"",
 	error: "s.\"error\"",
 	entityType: "s.\"entityType\"",
@@ -19306,6 +19313,7 @@ const TRACE_SELECT = `
   r."resourceId" AS "resourceId",
   r."startedAt" AS "startedAt",
   r."endedAt" AS "endedAt",
+  r."timeToFirstChunkMs" AS "timeToFirstChunkMs",
   r."entityName" AS "entityName",
   r."entityType" AS "entityType",
   r."environment" AS "environment",
@@ -19429,11 +19437,11 @@ function compileScalarPredicate(predicate, registry, parameterOffset, allowMetad
 		gte: ">="
 	};
 	if (predicate.operator === "eq") return {
-		sql: `${field} IS NOT DISTINCT FROM ${parameter}`,
+		sql: `${field} IS NOT NULL AND ${field} = ${parameter}`,
 		values: [...fieldValues, predicate.value]
 	};
 	if (predicate.operator === "ne") return {
-		sql: `${field} IS DISTINCT FROM ${parameter}`,
+		sql: `${field} IS NULL OR ${field} <> ${parameter}`,
 		values: [...fieldValues, predicate.value]
 	};
 	const operator = operators[predicate.operator];
@@ -19522,6 +19530,8 @@ const ROOT_PUSHDOWN_FIELDS = /* @__PURE__ */ new Set([
 	"endedAt",
 	"entityName",
 	"entityType",
+	"name",
+	"spanType",
 	"environment"
 ]);
 function isRootPushdownPredicate(predicate) {
@@ -19671,6 +19681,7 @@ function compilePostgresTraceScope(schema, selection, relationCollections, scope
         WHEN s."isPending" THEN NULL
         ELSE ${durationMsSql("s.\"startedAt\"", "s.\"endedAt\"")}
       END AS "durationMs",
+      s."timeToFirstChunkMs",
       CASE WHEN s."error" IS NOT NULL THEN 'error' ELSE 'success' END AS "status",
       s."error",
       s."entityType",
@@ -20045,6 +20056,7 @@ function traceRowToResult(row) {
 		resourceId: row.resourceId == null ? null : String(row.resourceId),
 		startedAt: asIsoTimestamp$1(row.startedAt),
 		endedAt: asIsoTimestamp$1(row.endedAt),
+		...timeToFirstChunkSupported && { timeToFirstChunkMs: row.timeToFirstChunkMs == null ? null : Number(row.timeToFirstChunkMs) },
 		entityName: row.entityName == null ? null : String(row.entityName),
 		entityType: row.entityType == null ? null : String(row.entityType),
 		environment: row.environment == null ? null : String(row.environment),
@@ -20164,6 +20176,9 @@ async function queryThreads(client, schema, plan, timeoutMs) {
 function compileSpanQueryPredicate(predicate, offset) {
 	return compileScalarPredicate(predicate, SPAN_QUERY_FIELDS, offset);
 }
+function compileThreadQueryPredicate(predicate, offset) {
+	return compileScalarPredicate(predicate, Object.fromEntries(Object.keys(_mastra_core_storage.THREAD_QUERY_FIELD_REGISTRY).map((field) => [field, `s."${field}"`])), offset);
+}
 //#endregion
 //#region src/storage/domains/observability/v-next/span-query.ts
 const identityFields = [
@@ -20197,7 +20212,8 @@ const fields = [
 	"serviceName",
 	"experimentId",
 	"environment",
-	"executionSource"
+	"executionSource",
+	"timeToFirstChunkMs"
 ];
 const identities = identityFields.map((field) => `"${field}"`).join(", ");
 const identityOrder = identityFields.map((field) => `"${field}" COLLATE "C" ASC NULLS LAST`).join(", ");
@@ -20313,8 +20329,9 @@ async function querySpans(client, schema, plan, timeoutMs) {
 	return runWithPostgresTraceQueryTimeout(client, timeoutMs, async (tx) => {
 		const query = compilePostgresSpanQuery(schema, plan);
 		const rows = await tx.any(query.text, query.values);
-		const selected = rows.map(({ version: _version, startedAt, endedAt, ...row }) => ({
+		const selected = rows.map(({ version: _version, startedAt, endedAt, timeToFirstChunkMs, ...row }) => ({
 			...row,
+			...timeToFirstChunkSupported && { timeToFirstChunkMs },
 			startedAt: startedAt.toISOString(),
 			endedAt: endedAt.toISOString()
 		}));
@@ -20361,11 +20378,245 @@ async function querySpans(client, schema, plan, timeoutMs) {
 	}, { repeatableRead: true });
 }
 //#endregion
+//#region src/storage/domains/observability/v-next/thread-query.ts
+const contextFields = [
+	"resourceId",
+	"userId",
+	"entityType",
+	"entityId",
+	"entityName",
+	"entityVersionId",
+	"runId",
+	"sessionId",
+	"requestId",
+	"serviceName",
+	"experimentId",
+	"environment",
+	"executionSource"
+];
+function predicateFields(predicate, fields = /* @__PURE__ */ new Set()) {
+	if (!predicate) return fields;
+	if (predicate.type === "boolean") for (const arg of predicate.args) predicateFields(arg, fields);
+	else if (predicate.type === "not") predicateFields(predicate.arg, fields);
+	else fields.add(predicate.field);
+	return fields;
+}
+function canUseThreadCandidates(probe) {
+	return Number(probe.threadCount) <= 16384 && Number(probe.traceCount) <= 1e5 && Number(probe.threadBytes) + Number(probe.traceBytes) <= 4 * 1024 * 1024;
+}
+function compilePostgresThreadRowsQuery(schema, plan, strategy = "full") {
+	const values = [plan.timeRange.from, plan.timeRange.to];
+	const scope = [];
+	if (plan.scope) {
+		values.push(plan.scope.organizationId);
+		scope.push(`"organizationId" = $${values.length}`);
+		if (plan.scope.resourceId !== void 0) {
+			values.push(plan.scope.resourceId);
+			scope.push(`"resourceId" = $${values.length}`);
+		}
+	}
+	const table = qualifiedTable(schema, TABLE_SPAN_EVENTS);
+	const timestamp = plan.timeRange.mode === "threads" ? plan.timeRange.field : "startedAt";
+	const identity = (field) => `"organizationId" IS NULL, COALESCE("organizationId", ''), "${field}"`;
+	const threadFilter = `(${identity("threadId")}) IN (SELECT ${identity("threadId")} FROM candidate_threads)`;
+	const scopedRoots = `scoped_roots AS NOT MATERIALIZED (
+    SELECT * FROM ${table} WHERE "parentSpanId" IS NULL ${scope.length ? `AND ${scope.join(" AND ")}` : ""}
+  )`;
+	const candidates = `candidate_threads AS MATERIALIZED (
+    SELECT DISTINCT "organizationId", "threadId" FROM scoped_roots
+    WHERE "threadId" IS NOT NULL AND "${timestamp}" >= $1 AND "${timestamp}" < $2
+    ${strategy === "probe" ? "LIMIT 16385" : ""}
+  ), candidate_traces AS MATERIALIZED (
+    SELECT DISTINCT "organizationId", "traceId" FROM scoped_roots WHERE ${threadFilter}
+    ${strategy === "probe" ? "LIMIT 100001" : ""}
+  )`;
+	if (strategy === "probe") return {
+		text: `WITH ${scopedRoots}, ${candidates}
+      SELECT (SELECT count(*) FROM candidate_threads) AS "threadCount",
+        (SELECT COALESCE(sum(octet_length(COALESCE("organizationId", '')) + octet_length("threadId")), 0) FROM candidate_threads) AS "threadBytes",
+        count(*) AS "traceCount", COALESCE(sum(octet_length(COALESCE("organizationId", '')) + octet_length("traceId")), 0) AS "traceBytes"
+      FROM candidate_traces`,
+		values
+	};
+	const predicate = plan.where ? compileThreadQueryPredicate(plan.where, values.length + 1) : {
+		sql: "TRUE",
+		values: []
+	};
+	values.push(...predicate.values);
+	let after = "TRUE";
+	if (plan.cursor) {
+		values.push(plan.cursor.sortValue);
+		const stamp = `$${values.length}::timestamptz`;
+		const field = `s."${plan.orderBy.field}"`;
+		const terms = [`${field} ${plan.orderBy.direction === "asc" ? ">" : "<"} ${stamp}`];
+		const equal = [`${field} = ${stamp}`];
+		for (const key of ["organizationId", "threadId"]) {
+			const ref = `s."${key}" COLLATE "C"`;
+			if (plan.cursor[key] === null) equal.push(`${ref} IS NULL`);
+			else {
+				values.push(plan.cursor[key]);
+				const value = `$${values.length}::text COLLATE "C"`;
+				terms.push(`(${equal.join(" AND ")} AND (${ref} > ${value} OR ${ref} IS NULL))`);
+				equal.push(`${ref} = ${value}`);
+			}
+		}
+		after = `(${terms.join(" OR ")})`;
+	}
+	const qualify = plan.timeRange.mode === "traces" ? "s.\"inWindow\"" : `s."${plan.timeRange.field}" >= $1 AND s."${plan.timeRange.field}" < $2`;
+	const filtered = predicateFields(plan.where);
+	const firstContext = [...contextFields, "timeToFirstChunkMs"].filter((field) => field === "resourceId" || filtered.has(field));
+	const lastFields = [
+		"traceId",
+		"spanId",
+		"cursorId",
+		"resourceId",
+		"endedAt",
+		...filtered.has("status") ? ["status"] : []
+	];
+	values.push(plan.limit + 1);
+	return {
+		text: `WITH ${scopedRoots}, ${strategy === "candidates" ? `${candidates}, ` : ""}current_roots AS (
+    SELECT DISTINCT ON ("organizationId", "traceId")
+      "organizationId", "threadId", "traceId", "spanId", "cursorId", "startedAt", "endedAt", "isPending",
+      ${firstContext.map((field) => field === "timeToFirstChunkMs" ? `CASE WHEN "spanType" = 'agent_run' THEN "timeToFirstChunkMs" END AS "timeToFirstChunkMs"` : `"${field}"`).join(", ")}
+      ${filtered.has("status") ? ", CASE WHEN error IS NULL THEN 'success' ELSE 'error' END AS status" : ""}
+    FROM scoped_roots ${strategy === "candidates" ? `WHERE (${identity("traceId")}) IN (SELECT ${identity("traceId")} FROM candidate_traces)` : ""}
+    ORDER BY "organizationId", "traceId", "startedAt" ASC, "spanId" COLLATE "C", "cursorId" DESC
+  ), ranked AS (
+    SELECT *, row_number() OVER first_order AS rank,
+      max("endedAt") OVER population AS "lastActivity", count(*) OVER population AS "traceCount",
+      bool_or("startedAt" >= $1 AND "startedAt" < $2) OVER population AS "inWindow",
+      ${lastFields.map((field) => `first_value("${field}") OVER last_order AS "last${field[0].toUpperCase()}${field.slice(1)}"`).join(", ")}
+    FROM current_roots WHERE NOT "isPending" AND "endedAt" IS NOT NULL AND "threadId" IS NOT NULL ${strategy === "candidates" ? `AND ${threadFilter}` : ""}
+    WINDOW population AS (PARTITION BY "organizationId", "threadId"),
+      first_order AS (PARTITION BY "organizationId", "threadId" ORDER BY "startedAt", "traceId" COLLATE "C"),
+      last_order AS (PARTITION BY "organizationId", "threadId" ORDER BY "startedAt" DESC, "traceId" COLLATE "C" DESC)
+  ), rows AS (
+    SELECT "organizationId", "threadId", "traceId" AS "firstTraceId", "spanId" AS "firstSpanId", "cursorId" AS "firstCursorId",
+      "endedAt" AS "firstEndedAt", "startedAt", "lastActivity" AS "endedAt", "traceCount", "inWindow",
+      ${firstContext.map((field) => `"${field}"`).join(", ")},
+      ${lastFields.map((field) => `"last${field[0].toUpperCase()}${field.slice(1)}"${field === "status" ? " AS status" : ""}`).join(", ")}
+    FROM ranked WHERE rank = 1
+  ) SELECT * FROM rows s WHERE ${qualify} AND (${predicate.sql}) AND ${after}
+    ORDER BY s."${plan.orderBy.field}" ${plan.orderBy.direction === "asc" ? "ASC" : "DESC"},
+      s."organizationId" COLLATE "C" ASC NULLS LAST, s."threadId" COLLATE "C" ASC LIMIT $${values.length}`,
+		values
+	};
+}
+async function queryThreadRows(client, schema, plan, timeoutMs, strategy = "auto") {
+	const deadline = performance.now() + _mastra_core_storage.resolveTraceQueryTimeoutMs(timeoutMs);
+	const run = async (text, values) => {
+		const remaining = Math.floor(deadline - performance.now());
+		if (remaining <= 0) throw new _mastra_core_storage.TraceQueryExecutionError();
+		return await runWithPostgresTraceQueryTimeout(client, remaining, (tx) => tx.any(text, values));
+	};
+	if (strategy === "auto") {
+		const probeQuery = compilePostgresThreadRowsQuery(schema, plan, "probe");
+		const [probe] = await run(probeQuery.text, probeQuery.values);
+		if (Number(probe.threadCount) === 0) return {
+			threads: [],
+			page: { next: null }
+		};
+		strategy = canUseThreadCandidates(probe) ? "candidates" : "full";
+	}
+	const compiled = compilePostgresThreadRowsQuery(schema, plan, strategy);
+	const selected = await run(compiled.text, compiled.values);
+	const page = selected.slice(0, plan.limit);
+	if (!page.length) return {
+		threads: [],
+		page: { next: null }
+	};
+	const table = qualifiedTable(schema, TABLE_SPAN_EVENTS);
+	const values = [];
+	const keys = page.flatMap((row) => ["first", "last"].map((which) => {
+		const entries = {
+			organizationId: row.organizationId,
+			resourceId: which === "first" ? row.resourceId : row.lastResourceId,
+			traceId: row[`${which}TraceId`],
+			spanId: row[`${which}SpanId`],
+			cursorId: row[`${which}CursorId`],
+			endedAt: row[`${which}EndedAt`]
+		};
+		return `(${Object.entries(entries).map(([field, value]) => {
+			values.push(value);
+			return `"${field}" ${field === "organizationId" || field === "resourceId" ? "IS NOT DISTINCT FROM" : "="} $${values.length}`;
+		}).join(" AND ")})`;
+	}));
+	const payloads = await run(`SELECT "organizationId", "traceId", "cursorId", "spanType", ${contextFields.map((field) => `"${field}"`).join(", ")},
+    CASE WHEN "spanType" = 'agent_run' THEN "timeToFirstChunkMs" END AS "timeToFirstChunkMs",
+    CASE WHEN error IS NULL THEN 'success' ELSE 'error' END AS status,
+    ${[
+		"input",
+		"output",
+		"error"
+	].map((field) => `"${field}Preview", CASE WHEN ${missingPreviewSql(`"${field}Preview"`)} THEN "${field}" END AS "${field}"`).join(", ")}
+    FROM ${table} WHERE ${keys.join(" OR ")}`, values);
+	const key = (org, trace, version) => JSON.stringify([
+		org,
+		trace,
+		String(version)
+	]);
+	const byRoot = new Map(payloads.map((row) => [key(row.organizationId, row.traceId, row.cursorId), row]));
+	const agents = page.filter((row) => byRoot.get(key(row.organizationId, row.firstTraceId, row.firstCursorId))?.spanType === "agent_run");
+	const models = /* @__PURE__ */ new Map();
+	if (agents.length) {
+		const modelValues = [];
+		const rows = await run(`SELECT DISTINCT ON ("organizationId", "traceId") "organizationId", "traceId",
+        CASE WHEN jsonb_typeof(attributes -> 'model') = 'string' THEN attributes ->> 'model' END AS model,
+        CASE WHEN jsonb_typeof(attributes -> 'provider') = 'string' THEN attributes ->> 'provider' END AS provider
+        FROM ${table} WHERE "spanType" = 'model_generation' AND NOT "isPending" AND (${agents.map((row) => `(${Object.entries({
+			organizationId: row.organizationId,
+			resourceId: row.resourceId,
+			traceId: row.firstTraceId,
+			parentSpanId: row.firstSpanId
+		}).map(([field, value]) => {
+			modelValues.push(value);
+			return `"${field}" ${field === "organizationId" || field === "resourceId" ? "IS NOT DISTINCT FROM" : "="} $${modelValues.length}`;
+		}).join(" AND ")})`).join(" OR ")})
+        ORDER BY "organizationId", "traceId", "startedAt", "spanId" COLLATE "C", "cursorId" DESC`, modelValues);
+		for (const row of rows) models.set(JSON.stringify([row.organizationId, row.traceId]), row);
+	}
+	const threads = page.flatMap((row) => {
+		const first = byRoot.get(key(row.organizationId, row.firstTraceId, row.firstCursorId));
+		const last = byRoot.get(key(row.organizationId, row.lastTraceId, row.lastCursorId));
+		if (!first || !last) return [];
+		const model = models.get(JSON.stringify([row.organizationId, row.firstTraceId]));
+		return [_mastra_core_storage.threadQueryRowSchema.parse({
+			organizationId: row.organizationId,
+			threadId: row.threadId,
+			firstTraceId: row.firstTraceId,
+			lastTraceId: row.lastTraceId,
+			...Object.fromEntries(contextFields.map((field) => [field, first[field]])),
+			status: last.status,
+			startedAt: row.startedAt.toISOString(),
+			endedAt: row.endedAt.toISOString(),
+			traceCount: Number(row.traceCount),
+			timeToFirstChunkMs: first.timeToFirstChunkMs,
+			model: model?.model ?? null,
+			provider: model?.provider ?? null,
+			inputPreview: readPreview(first.inputPreview, first.input),
+			outputPreview: readPreview(last.outputPreview, last.output),
+			errorPreview: readPreview(last.errorPreview, last.error)
+		})];
+	});
+	const last = page.at(-1);
+	return {
+		threads,
+		page: { next: selected.length > plan.limit ? _mastra_core_storage.encodeThreadQueryCursor(plan, {
+			organizationId: last.organizationId,
+			threadId: last.threadId,
+			sortValue: last[plan.orderBy.field].toISOString()
+		}) : null }
+	};
+}
+//#endregion
 //#region src/storage/domains/observability/v-next/trace-aggregate.ts
 /** Trace-root column expressions (alias `r`) for each groupable dimension; same values `where` sees. */
 const DIMENSION_SQL = {
 	entityType: "r.\"entityType\"",
 	entityName: "r.\"entityName\"",
+	name: "r.\"name\"",
+	spanType: "r.\"spanType\"",
 	environment: "r.\"environment\"",
 	status: TRACE_STATUS_SQL,
 	serviceName: "r.\"serviceName\"",
@@ -21592,12 +21843,15 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"trace-query",
 			"trace-aggregate",
 			...spanQueryFeatures,
+			...typeof _mastra_core_storage.planThreadRowsQuery === "function" ? ["thread-query-rows"] : [],
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
 			"trace-query-tenant-scope",
 			"feedback",
-			"trace-query-context-ids"
+			"trace-query-context-ids",
+			...timeToFirstChunkFeatures,
+			"trace-query-root-span-fields"
 		];
 		return [
 			"metrics",
@@ -21612,12 +21866,15 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"trace-query",
 			"trace-aggregate",
 			...spanQueryFeatures,
+			...typeof _mastra_core_storage.planThreadRowsQuery === "function" ? ["thread-query-rows"] : [],
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
 			"trace-query-tenant-scope",
 			"feedback",
-			"trace-query-context-ids"
+			"trace-query-context-ids",
+			...timeToFirstChunkFeatures,
+			"trace-query-root-span-fields"
 		];
 	}
 	async #run(op, fn, details) {
@@ -21679,7 +21936,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 		return this.#run("GET_TRACE_QUERY_VALUES", () => getTraceQueryValues(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
 	}
 	async queryThreads(plan) {
-		return this.#run("QUERY_THREADS", () => queryThreads(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
+		return this.#run("QUERY_THREADS", () => plan.result === "threadRows" ? queryThreadRows(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs) : queryThreads(this.#readClient, this.#schema, plan, this.#traceQueryTimeoutMs));
 	}
 	async listBranches(args) {
 		return this.#run("LIST_BRANCHES", () => listBranches(this.#readClient, this.#schema, args));
@@ -24111,7 +24368,7 @@ var SkillsPG = class SkillsPG extends _mastra_core_storage.SkillsStorage {
 		}
 	}
 	async list(args) {
-		const { page = 0, perPage: perPageInput, orderBy, authorId, visibility, status, entityIds, pinFavoritedFor, favoritedOnly } = args || {};
+		const { page = 0, perPage: perPageInput, orderBy, authorId, visibility, status, entityIds, pinFavoritedFor, favoritedOnly, metadata } = args || {};
 		const { field, direction } = this.parseOrderBy(orderBy);
 		if (page < 0) throw new _mastra_core_error.MastraError({
 			id: (0, _mastra_core_storage.createStorageErrorId)("PG", "LIST_SKILLS", "INVALID_PAGE"),
@@ -24156,6 +24413,16 @@ var SkillsPG = class SkillsPG extends _mastra_core_storage.SkillsStorage {
 				conditions.push(`s.visibility = $${paramIdx++}`);
 				queryParams.push(visibility);
 			}
+			if (metadata && Object.keys(metadata).length > 0) {
+				const versionsTable = getTableName$5({
+					indexName: _mastra_core_storage.TABLE_SKILL_VERSIONS,
+					schemaName: getSchemaName$5(this.#schema)
+				});
+				const latestVersionId = `(SELECT lv.id FROM ${versionsTable} lv WHERE lv."skillId" = s.id ORDER BY lv."versionNumber" DESC LIMIT 1)`;
+				const resolvedVersionId = status === "draft" ? latestVersionId : `COALESCE(s."activeVersionId", ${latestVersionId})`;
+				conditions.push(`EXISTS (SELECT 1 FROM ${versionsTable} mv WHERE mv."skillId" = s.id AND mv.id = ${resolvedVersionId} AND mv.metadata @> $${paramIdx++}::jsonb)`);
+				queryParams.push(toPgJson(metadata));
+			}
 			if (entityIds && entityIds.length > 0) {
 				const placeholders = entityIds.map(() => `$${paramIdx++}`).join(", ");
 				conditions.push(`s.id IN (${placeholders})`);