@mastra/pg 1.35.0-alpha.1 → 1.35.0-alpha.3

package/dist/_types/{@internal_core → @internal_core@0.1.4}/dist/knowledge-compat/index.d.ts

@@ -318,6 +318,7 @@ export interface KnowledgePagesCore {
   MAX_KNOWLEDGE_MOVE_PAGES: number;
   MAX_KNOWLEDGE_PAGE_DEPTH: number;
   MAX_KNOWLEDGE_PAGE_LIST_LIMIT: number;
+  MAX_KNOWLEDGE_PAGE_LINKS: number;
   KnowledgeMoveTooLargeError: new (pageId: string, pages: number) => Error;
   KnowledgePageDepthError: new (pageId: string) => Error;
   KnowledgePageHasChildrenError: new (pageId: string) => Error;
@@ -325,11 +326,25 @@ export interface KnowledgePagesCore {
 }
 /** Loads core's page-store runtime once, after checking core advertises `knowledge-pages`. */
 export declare function createKnowledgePagesCoreLoader(features: ReadonlySet<string>, loadStorageModule: () => Promise<unknown>): () => Promise<KnowledgePagesCore>;
+/** Most words one keyword search uses; every word adds a substring check per page in each store. */
+export declare const KNOWLEDGE_SEARCH_MAX_WORDS = 16;
 /**
- * Keyword-search words: the query split on whitespace, lowercased, deduplicated. Every word must
- * appear (as a case-insensitive substring) in a hit; an empty list means the search returns nothing.
+ * Keyword-search words: the query split on whitespace, lowercased, deduplicated, keeping the first
+ * {@link KNOWLEDGE_SEARCH_MAX_WORDS}. A hit needs at least one of them (as a case-insensitive
+ * substring); an empty list means the search returns nothing.
  */
 export declare function knowledgeSearchWords(query: string): string[];
+/**
+ * Points one matched search word earns on a page, by the best field it appears in: name, then
+ * description, then body. A page whose name contains the whole query ranks first; below that, pages
+ * rank by how many query words they match, and these points only break ties between pages that
+ * match the same number of words.
+ */
+export declare const KNOWLEDGE_SEARCH_WEIGHTS: {
+  readonly name: 3;
+  readonly description: 2;
+  readonly body: 1;
+};
 /**
  * Why `key` can't be a Knowledge page key, or undefined when it can. Keys are one path segment:
  * non-empty, with no `/` (path separator), `#` (scope/path separator) or `%` (escape character).

package/dist/index.cjs

@@ -4466,7 +4466,8 @@ var AgentsPG = class AgentsPG extends _mastra_core_storage.AgentsStorage {
 				"skillsFormat",
 				"durable",
 				"browser",
-				"toolProviders"
+				"toolProviders",
+				"modelList"
 			]
 		});
 		await this.#migrateToolsToJsonbFormat();
@@ -4524,10 +4525,10 @@ var AgentsPG = class AgentsPG extends _mastra_core_storage.AgentsStorage {
 				row.updatedAt ?? now
 			]);
 			await this.#db.client.none(`INSERT INTO ${fullVersionsTableName}
-         (id, "agentId", "versionNumber", name, description, instructions, model, tools,
+         (id, "agentId", "versionNumber", name, description, instructions, model, "modelList", tools,
           "defaultOptions", workflows, agents, "integrationTools", "toolProviders", "inputProcessors",
           "outputProcessors", memory, scorers, "changedFields", "changeMessage", "createdAt")
-         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21)
          ON CONFLICT (id) DO NOTHING`, [
 				versionId,
 				agentId,
@@ -4536,6 +4537,7 @@ var AgentsPG = class AgentsPG extends _mastra_core_storage.AgentsStorage {
 				row.description ?? null,
 				this.serializeInstructions(row.instructions ?? ""),
 				row.model ? toPgJson(row.model) : "{}",
+				row.modelList ? toPgJson(row.modelList) : null,
 				row.tools ? toPgJson(row.tools) : null,
 				row.defaultOptions ? toPgJson(row.defaultOptions) : null,
 				row.workflows ? toPgJson(row.workflows) : null,
@@ -4949,21 +4951,22 @@ var AgentsPG = class AgentsPG extends _mastra_core_storage.AgentsStorage {
 			const nowIso = (/* @__PURE__ */ new Date()).toISOString();
 			const row = await this.#db.client.one(`INSERT INTO ${tableName} (
           id, "agentId", "versionNumber",
-          name, description, instructions, model, tools,
+          name, description, instructions, model, "modelList", tools,
           "defaultOptions", workflows, agents, "integrationTools", "toolProviders",
           "inputProcessors", "outputProcessors", memory, scorers,
           "mcpClients", "requestContextSchema", workspace, skills, "skillsFormat",
           durable, browser,
           "changedFields", "changeMessage",
           "createdAt", "createdAtZ"
-        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28) RETURNING *`, [
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28, $29) RETURNING *`, [
 				input.id,
 				input.agentId,
 				input.versionNumber,
 				input.name,
 				input.description ?? null,
-				this.serializeInstructions(input.instructions),
-				toPgJson(input.model),
+				this.serializeInstructions(input.instructions) ?? "",
+				toPgJson(input.model ?? {}),
+				input.modelList ? toPgJson(input.modelList) : null,
 				input.tools ? toPgJson(input.tools) : null,
 				input.defaultOptions ? toPgJson(input.defaultOptions) : null,
 				input.workflows ? toPgJson(input.workflows) : null,
@@ -5209,6 +5212,7 @@ var AgentsPG = class AgentsPG extends _mastra_core_storage.AgentsStorage {
 			description: row.description,
 			instructions: this.deserializeInstructions(row.instructions),
 			model: parseJsonResilient(row.model, "model"),
+			modelList: parseJsonResilient(row.modelList, "modelList"),
 			tools: parseJsonResilient(row.tools, "tools"),
 			defaultOptions: parseJsonResilient(row.defaultOptions, "defaultOptions"),
 			workflows: parseJsonResilient(row.workflows, "workflows"),
@@ -8645,7 +8649,8 @@ const KNOWLEDGE_PAGES_CORE_FUNCTIONS = [
 const KNOWLEDGE_PAGES_CORE_NUMBERS = [
 	"MAX_KNOWLEDGE_MOVE_PAGES",
 	"MAX_KNOWLEDGE_PAGE_DEPTH",
-	"MAX_KNOWLEDGE_PAGE_LIST_LIMIT"
+	"MAX_KNOWLEDGE_PAGE_LIST_LIMIT",
+	"MAX_KNOWLEDGE_PAGE_LINKS"
 ];
 function resolveKnowledgePagesCore(storageModule) {
 	const module = typeof storageModule === "object" && storageModule !== null ? storageModule : {};
@@ -8666,13 +8671,25 @@ function createKnowledgePagesCoreLoader(features, loadStorageModule) {
 	};
 }
 /**
-* Keyword-search words: the query split on whitespace, lowercased, deduplicated. Every word must
-* appear (as a case-insensitive substring) in a hit; an empty list means the search returns nothing.
+* Keyword-search words: the query split on whitespace, lowercased, deduplicated, keeping the first
+* {@link KNOWLEDGE_SEARCH_MAX_WORDS}. A hit needs at least one of them (as a case-insensitive
+* substring); an empty list means the search returns nothing.
 */
 function knowledgeSearchWords(query) {
-	return [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))];
+	return [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))].slice(0, 16);
 }
 /**
+* Points one matched search word earns on a page, by the best field it appears in: name, then
+* description, then body. A page whose name contains the whole query ranks first; below that, pages
+* rank by how many query words they match, and these points only break ties between pages that
+* match the same number of words.
+*/
+const KNOWLEDGE_SEARCH_WEIGHTS = {
+	name: 3,
+	description: 2,
+	body: 1
+};
+/**
 * Why `key` can't be a Knowledge page key, or undefined when it can. Keys are one path segment:
 * non-empty, with no `/` (path separator), `#` (scope/path separator) or `%` (escape character).
 */
@@ -8691,7 +8708,8 @@ const PG_KNOWLEDGE_PAGES_TABLES = {
 	mentions: "mastra_knowledge_mentions",
 	pins: "mastra_knowledge_pins",
 	activity: "mastra_knowledge_activity",
-	state: "mastra_knowledge_access_state"
+	state: "mastra_knowledge_access_state",
+	links: "mastra_knowledge_page_links"
 };
 /**
 * Schema-4 DDL. `COLLATE "C"` on every column that is ordered, prefix-matched or compared for
@@ -8750,7 +8768,9 @@ function pgKnowledgePagesDDL(schemaName) {
     )`,
 		`CREATE TABLE IF NOT EXISTS ${q(t.pins)} (
       "id" text PRIMARY KEY,
-      "pageId" text NOT NULL UNIQUE REFERENCES ${q(t.pages)} ("id"),
+      "pageId" text NOT NULL REFERENCES ${q(t.pages)} ("id"),
+      "kind" text NOT NULL DEFAULT 'page',
+      "depth" integer,
       "audience" text[] NOT NULL,
       "createdBy" text NOT NULL,
       "createdAt" timestamptz NOT NULL,
@@ -8782,6 +8802,19 @@ function pgKnowledgePagesDDL(schemaName) {
 		index("mastra_knowledge_mentions_page_idx", t.mentions, "\"pageId\""),
 		`CREATE INDEX IF NOT EXISTS "mastra_knowledge_pins_audience_gin" ON ${q(t.pins)} USING gin ("audience")`,
 		index("mastra_knowledge_pins_created_idx", t.pins, "\"createdAt\",\"id\""),
+		`ALTER TABLE ${q(t.pins)} ADD COLUMN IF NOT EXISTS "kind" text NOT NULL DEFAULT 'page'`,
+		`ALTER TABLE ${q(t.pins)} ADD COLUMN IF NOT EXISTS "depth" integer`,
+		`ALTER TABLE ${q(t.pins)} DROP CONSTRAINT IF EXISTS "${t.pins}_pageId_key"`,
+		index("mastra_knowledge_pins_page_kind_idx", t.pins, "\"pageId\",\"kind\"", "", true),
+		`CREATE TABLE IF NOT EXISTS ${q(t.links)} (
+      "fromPageId" text NOT NULL,
+      "ref" text COLLATE "C" NOT NULL,
+      "toPageId" text,
+      "count" integer NOT NULL,
+      PRIMARY KEY ("fromPageId", "ref")
+    )`,
+		index("mastra_knowledge_page_links_to_idx", t.links, "\"toPageId\"", "\"toPageId\" IS NOT NULL"),
+		index("mastra_knowledge_page_links_ref_idx", t.links, "\"ref\"", "\"toPageId\" IS NULL"),
 		index("mastra_knowledge_activity_page_idx", t.activity, "\"pageId\",\"createdAt\",\"id\""),
 		index("mastra_knowledge_activity_created_idx", t.activity, "\"createdAt\",\"id\"")
 	];
@@ -8926,6 +8959,8 @@ function toPin(row) {
 	return {
 		id: String(row.id),
 		pageId: String(row.pageId),
+		kind: String(row.kind),
+		...row.depth == null ? {} : { depth: Number(row.depth) },
 		audience: row.audience ?? [],
 		createdBy: String(row.createdBy),
 		createdAt: new Date(row.createdAt),
@@ -8977,6 +9012,9 @@ var PgKnowledgePages = class {
 	get #pins() {
 		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.pins);
 	}
+	get #links() {
+		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.links);
+	}
 	get #activity() {
 		return this.#q(PG_KNOWLEDGE_PAGES_TABLES.activity);
 	}
@@ -9213,6 +9251,7 @@ var PgKnowledgePages = class {
 		const params = new Params();
 		const where = [`"isScope"`, `"deletedAt" IS NULL`];
 		where.push(input.parentId === null ? `"parentId" IS NULL` : `"parentId" = ${params.add(input.parentId)}`);
+		if (input.read && input.read !== "all") where.push(`"id" IN (${new ReadFilter(input.read, params, this.#pages).readableIds()})`);
 		if (input.cursor) {
 			const [position, id] = decodeCursor(input.cursor, 2);
 			where.push(`("position", "id") > (${params.add(position)}, ${params.add(id)})`);
@@ -9488,9 +9527,17 @@ var PgKnowledgePages = class {
 			await tx.query(`UPDATE ${this.#notes} SET "pageId" = $2 WHERE "pageId" = $1`, [source.id, target.id]);
 			await tx.query(`DELETE FROM ${this.#mentions} m WHERE m."pageId" = $1 AND EXISTS (SELECT 1 FROM ${this.#mentions} t WHERE t."noteId" = m."noteId" AND t."pageId" = $2)`, [source.id, target.id]);
 			await tx.query(`UPDATE ${this.#mentions} SET "pageId" = $2 WHERE "pageId" = $1`, [source.id, target.id]);
-			const sourcePin = (await this.#rows(tx, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 FOR UPDATE`, [source.id]))[0];
-			if (sourcePin) {
-				await this.#upsertPinAudience(tx, target.id, sourcePin.audience ?? [], String(sourcePin.createdBy), now);
+			const sourcePins = await this.#rows(tx, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 ORDER BY "kind" FOR UPDATE`, [source.id]);
+			for (const sourcePin of sourcePins) {
+				await this.#upsertPinAudience(tx, {
+					pageId: target.id,
+					kind: String(sourcePin.kind),
+					depth: sourcePin.depth == null ? null : Number(sourcePin.depth),
+					audience: sourcePin.audience ?? [],
+					createdBy: String(sourcePin.createdBy),
+					now,
+					keepDepth: true
+				});
 				await tx.query(`DELETE FROM ${this.#pins} WHERE "id" = $1`, [String(sourcePin.id)]);
 			}
 			const rows = await this.#rows(tx, `SELECT * FROM ${this.#pages} WHERE "id" = $1`, [target.id]);
@@ -9550,6 +9597,118 @@ var PgKnowledgePages = class {
 		const rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()} FROM ${this.#visibleNotes(filter)} AND ${extra.join(" AND ")} ORDER BY n."createdAt", n."id" LIMIT ${limit + 1}`, params.values);
 		return this.#noteOutput(rows, limit);
 	}
+	async countChildScopes(input) {
+		const ids = [...new Set(input.parentIds)];
+		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
+		if (!ids.length) return counts;
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const rows = await this.#rows(this.#client, `SELECT s."parentId" AS "parentId", count(*)::int AS "count" FROM ${this.#pages} s
+       WHERE s."parentId" = ANY(${params.add(ids)}::text[]) AND s."isScope" AND s."deletedAt" IS NULL AND ${filter.readable("s")}
+       GROUP BY s."parentId"`, params.values);
+		for (const row of rows) counts[row.parentId] = Number(row.count);
+		return counts;
+	}
+	async countChildPages(input) {
+		const ids = [...new Set(input.parentIds)];
+		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
+		if (!ids.length) return counts;
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const rows = await this.#rows(this.#client, `SELECT p."parentId" AS "parentId", count(*)::int AS "count" FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId"
+       WHERE p."parentId" = ANY(${params.add(ids)}::text[]) AND NOT p."isScope" AND p."deletedAt" IS NULL AND ${filter.readable("s")}
+       GROUP BY p."parentId"`, params.values);
+		for (const row of rows) counts[row.parentId] = Number(row.count);
+		return counts;
+	}
+	async replacePageBodyLinks(input) {
+		await this.#tx(async (tx) => {
+			await tx.query(`DELETE FROM ${this.#links} WHERE "fromPageId" = $1`, [input.pageId]);
+			if (!input.links.length) return;
+			await tx.query(`INSERT INTO ${this.#links} ("fromPageId","ref","toPageId","count") SELECT $1, r, t, c FROM unnest($2::text[], $3::text[], $4::int[]) AS x(r, t, c)`, [
+				input.pageId,
+				input.links.map((l) => l.ref),
+				input.links.map((l) => l.toPageId),
+				input.links.map((l) => l.count)
+			]);
+		});
+	}
+	async listPageBodyLinkSources(input) {
+		const refs = [...new Set(input.refs ?? [])];
+		const targets = [...new Set(input.toPageIds ?? [])];
+		if (!refs.length && !targets.length) return [];
+		const parts = [];
+		const params = new Params();
+		if (refs.length) parts.push(`("toPageId" IS NULL AND "ref" = ANY(${params.add(refs)}::text[]))`);
+		if (targets.length) parts.push(`"toPageId" = ANY(${params.add(targets)}::text[])`);
+		return (await this.#rows(this.#client, `SELECT DISTINCT "fromPageId" FROM ${this.#links} WHERE ${parts.join(" OR ")}`, params.values)).map((row) => String(row.fromPageId));
+	}
+	/**
+	* Every resolved link touching `ids` whose both ends are live and readable, one row per
+	* (from, to, kind); no self-links. Note links go through the same visible-note rule as listNotes.
+	*/
+	#visibleLinkEdges(filter, params, ids, direction, kinds) {
+		const wanted = new Set(kinds ?? ["body", "note"]);
+		const idsParam = `${params.add(ids)}::text[]`;
+		const touch = (from, to) => direction === "out" ? `${from} = ANY(${idsParam})` : direction === "in" ? `${to} = ANY(${idsParam})` : `(${from} = ANY(${idsParam}) OR ${to} = ANY(${idsParam}))`;
+		const branches = [];
+		if (wanted.has("body")) branches.push(`SELECT l."fromPageId" AS "fromPageId", l."toPageId" AS "toPageId", 'body'::text AS "kind", sum(l."count")::int AS "count"
+        FROM ${this.#links} l
+        JOIN ${this.#pages} fp ON fp."id" = l."fromPageId" AND fp."deletedAt" IS NULL
+        JOIN ${this.#pages} fs ON fs."id" = fp."scopeId"
+        JOIN ${this.#pages} tp ON tp."id" = l."toPageId" AND tp."deletedAt" IS NULL
+        JOIN ${this.#pages} ts ON ts."id" = tp."scopeId"
+        WHERE l."toPageId" IS NOT NULL AND l."fromPageId" <> l."toPageId" AND ${touch("l.\"fromPageId\"", "l.\"toPageId\"")}
+          AND ${filter.readable("fs")} AND ${filter.readable("ts")}
+        GROUP BY l."fromPageId", l."toPageId"`);
+		if (wanted.has("note")) branches.push(`SELECT vn."pageId" AS "fromPageId", mn."pageId" AS "toPageId", 'note'::text AS "kind", count(*)::int AS "count"
+        FROM (SELECT n."id", n."pageId" FROM ${this.#visibleNotes(filter)}
+          AND n."deletedAt" IS NULL AND np."deletedAt" IS NULL
+          AND (n."pageId" = ANY(${idsParam}) OR n."id" IN (SELECT mm."noteId" FROM ${this.#mentions} mm WHERE mm."pageId" = ANY(${idsParam})))) vn
+        JOIN ${this.#mentions} mn ON mn."noteId" = vn."id"
+        JOIN ${this.#pages} tp ON tp."id" = mn."pageId" AND tp."deletedAt" IS NULL
+        JOIN ${this.#pages} ts ON ts."id" = tp."scopeId"
+        WHERE mn."pageId" <> vn."pageId" AND ${touch("vn.\"pageId\"", "mn.\"pageId\"")} AND ${filter.readable("ts")}
+        GROUP BY vn."pageId", mn."pageId"`);
+		return branches.length ? branches.join(" UNION ALL ") : `SELECT NULL::text AS "fromPageId", NULL::text AS "toPageId", NULL::text AS "kind", NULL::int AS "count" WHERE FALSE`;
+	}
+	async countPageLinks(input) {
+		const ids = [...new Set(input.pageIds)];
+		const counts = Object.fromEntries(ids.map((id) => [id, {
+			in: 0,
+			out: 0
+		}]));
+		if (!ids.length) return counts;
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const edges = this.#visibleLinkEdges(filter, params, ids, "both", input.kinds);
+		const rows = await this.#rows(this.#client, `WITH e AS (${edges}), r AS (
+         SELECT "fromPageId" AS "id", count(DISTINCT "toPageId")::int AS "out", 0 AS "in" FROM e WHERE "fromPageId" = ANY(${params.add(ids)}::text[]) GROUP BY "fromPageId"
+         UNION ALL
+         SELECT "toPageId", 0, count(DISTINCT "fromPageId")::int FROM e WHERE "toPageId" = ANY(${params.add(ids)}::text[]) GROUP BY "toPageId")
+       SELECT "id", sum("out")::int AS "out", sum("in")::int AS "in" FROM r GROUP BY "id"`, params.values);
+		for (const row of rows) counts[String(row.id)] = {
+			in: Number(row.in),
+			out: Number(row.out)
+		};
+		return counts;
+	}
+	async listPageLinks(input) {
+		const limit = input.limit ?? 1e3;
+		if (!Number.isInteger(limit) || limit < 1) throw new RangeError("Knowledge link limit must be a positive integer");
+		const core = await loadPagesCore();
+		const ids = [...new Set(input.pageIds)];
+		if (!ids.length) return [];
+		const params = new Params();
+		const filter = new ReadFilter(input.read, params, this.#pages);
+		const edges = this.#visibleLinkEdges(filter, params, ids, input.direction ?? "both", input.kinds);
+		return (await this.#rows(this.#client, `SELECT * FROM (${edges}) e ORDER BY "fromPageId" COLLATE "C", "toPageId" COLLATE "C", CASE "kind" WHEN 'body' THEN 0 ELSE 1 END LIMIT ${Math.min(limit, core.MAX_KNOWLEDGE_PAGE_LINKS)}`, params.values)).map((row) => ({
+			fromPageId: String(row.fromPageId),
+			toPageId: String(row.toPageId),
+			kind: row.kind,
+			count: Number(row.count)
+		}));
+	}
 	async countNotes(input) {
 		const ids = [...new Set(input.pageIds)];
 		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
@@ -9664,7 +9823,7 @@ var PgKnowledgePages = class {
 	async removeNote(input) {
 		return this.#tx(async (tx) => {
 			const note = await this.#noteById(tx, input.id, true);
-			if (note.deletedAt) return note;
+			if (note.deletedAt) throw new _mastra_core_storage.KnowledgeNotFoundError("note", input.id);
 			const now = /* @__PURE__ */ new Date();
 			await tx.query(`UPDATE ${this.#notes} SET "deletedAt" = $2, "deletedBy" = $3, "version" = "version" + 1, "updatedAt" = $2 WHERE "id" = $1`, [
 				input.id,
@@ -9717,9 +9876,12 @@ var PgKnowledgePages = class {
 				filter.readable("s")
 			];
 			if (input.scopeIds?.length) where.push(`p."scopeId" = ANY(${params.add(input.scopeIds)}::text[])`);
-			for (const pattern of patterns) where.push(`(p."name" ILIKE ${pattern} OR p."description" ILIKE ${pattern} OR p."body" ILIKE ${pattern})`);
-			const tier = `CASE WHEN p."canonicalName" LIKE ${phrasePattern} THEN 0 WHEN ${patterns.map((pattern) => `p."name" ILIKE ${pattern}`).join(" AND ")} THEN 1 ELSE 2 END`;
-			const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId" WHERE ${where.join(" AND ")} ORDER BY ${tier}, p."updatedAt" DESC, p."id" ASC LIMIT ${limit}`, params.values);
+			const anyField = patterns.map((pattern) => `(p."name" ILIKE ${pattern} OR p."description" ILIKE ${pattern} OR p."body" ILIKE ${pattern})`).join(" OR ");
+			where.push(`(${anyField})`);
+			const score = patterns.map((pattern) => `(CASE WHEN p."name" ILIKE ${pattern} THEN ${KNOWLEDGE_SEARCH_WEIGHTS.name} WHEN p."description" ILIKE ${pattern} THEN ${KNOWLEDGE_SEARCH_WEIGHTS.description} WHEN p."body" ILIKE ${pattern} THEN ${KNOWLEDGE_SEARCH_WEIGHTS.body} ELSE 0 END)`).join(" + ");
+			const count = patterns.map((pattern) => `(CASE WHEN p."name" ILIKE ${pattern} OR p."description" ILIKE ${pattern} OR p."body" ILIKE ${pattern} THEN 1 ELSE 0 END)`).join(" + ");
+			const tier = `CASE WHEN p."canonicalName" LIKE ${phrasePattern} THEN 0 ELSE 1 END`;
+			const rows = await this.#rows(this.#client, `SELECT p.* FROM ${this.#pages} p JOIN ${this.#pages} s ON s."id" = p."scopeId" WHERE ${where.join(" AND ")} ORDER BY ${tier}, (${count}) DESC, (${score}) DESC, p."updatedAt" DESC, p."id" ASC LIMIT ${limit}`, params.values);
 			for (const row of rows) hits.push({
 				type: "page",
 				page: toPage(row)
@@ -9731,8 +9893,10 @@ var PgKnowledgePages = class {
 			const filter = new ReadFilter(input.read, params, this.#pages);
 			const extra = [`n."deletedAt" IS NULL`, `np."deletedAt" IS NULL`];
 			if (input.scopeIds?.length) extra.push(`np."scopeId" = ANY(${params.add(input.scopeIds)}::text[])`);
-			for (const word of words) extra.push(`n."text" ILIKE ${params.add(`%${escapeLike(word)}%`)}`);
-			const rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()}, row_to_json(np) AS "pageJson" FROM ${this.#visibleNotes(filter)} AND ${extra.join(" AND ")} ORDER BY n."updatedAt" DESC, n."id" DESC LIMIT ${limit - hits.length}`, params.values);
+			const noteHas = words.map((word) => `n."text" ILIKE ${params.add(`%${escapeLike(word)}%`)}`);
+			extra.push(`(${noteHas.join(" OR ")})`);
+			const noteScore = noteHas.map((has) => `(CASE WHEN ${has} THEN 1 ELSE 0 END)`).join(" + ");
+			const rows = await this.#rows(this.#client, `SELECT ${this.#noteColumns()}, row_to_json(np) AS "pageJson" FROM ${this.#visibleNotes(filter)} AND ${extra.join(" AND ")} ORDER BY (${noteScore}) DESC, n."updatedAt" DESC, n."id" DESC LIMIT ${limit - hits.length}`, params.values);
 			for (const row of rows) hits.push({
 				type: "note",
 				note: toNote(row),
@@ -9771,10 +9935,18 @@ var PgKnowledgePages = class {
 		};
 	}
 	async addPinAudience(input) {
+		const kind = input.kind ?? "page";
 		return this.#tx(async (tx) => {
 			const page = await this.#requireLivePage(tx, input.pageId, false);
 			const now = /* @__PURE__ */ new Date();
-			const { pin, changed } = await this.#upsertPinAudience(tx, page.id, input.audience, input.createdBy, now);
+			const { pin, changed } = await this.#upsertPinAudience(tx, {
+				pageId: page.id,
+				kind,
+				depth: kind === "list" ? input.depth ?? 1 : null,
+				audience: input.audience,
+				createdBy: input.createdBy,
+				now
+			});
 			if (changed) await this.#logActivity(tx, {
 				action: "pin-added",
 				scopeId: page.scopeId,
@@ -9785,28 +9957,35 @@ var PgKnowledgePages = class {
 			return pin;
 		});
 	}
-	async #upsertPinAudience(db, pageId, audience, createdBy, now) {
-		const existing = (await this.#rows(db, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 FOR UPDATE`, [pageId]))[0];
+	/** `keepDepth` (merges) leaves an existing pin's depth as it is instead of setting `depth`. */
+	async #upsertPinAudience(db, input) {
+		const { pageId, kind, audience, now } = input;
+		const existing = (await this.#rows(db, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 AND "kind" = $2 FOR UPDATE`, [pageId, kind]))[0];
 		if (!existing) return {
-			pin: toPin((await this.#rows(db, `INSERT INTO ${this.#pins} ("id","pageId","audience","createdBy","createdAt","updatedAt") VALUES ($1,$2,$3::text[],$4,$5,$5) RETURNING *`, [
+			pin: toPin((await this.#rows(db, `INSERT INTO ${this.#pins} ("id","pageId","kind","depth","audience","createdBy","createdAt","updatedAt") VALUES ($1,$2,$3,$4,$5::text[],$6,$7,$7) RETURNING *`, [
 				(0, _mastra_core_storage.createKnowledgeUlid)(),
 				pageId,
+				kind,
+				input.depth,
 				[...new Set(audience)],
-				createdBy,
+				input.createdBy,
 				iso(now)
 			]))[0]),
 			changed: true
 		};
 		const current = existing.audience ?? [];
 		const merged = [.../* @__PURE__ */ new Set([...current, ...audience])];
-		if (merged.length === current.length) return {
+		const currentDepth = existing.depth == null ? null : Number(existing.depth);
+		const depth = input.keepDepth ? currentDepth : input.depth;
+		if (merged.length === current.length && depth === currentDepth) return {
 			pin: toPin(existing),
 			changed: false
 		};
 		return {
-			pin: toPin((await this.#rows(db, `UPDATE ${this.#pins} SET "audience" = $2::text[], "updatedAt" = $3 WHERE "id" = $1 RETURNING *`, [
+			pin: toPin((await this.#rows(db, `UPDATE ${this.#pins} SET "audience" = $2::text[], "depth" = $3, "updatedAt" = $4 WHERE "id" = $1 RETURNING *`, [
 				String(existing.id),
 				merged,
+				depth,
 				iso(now)
 			]))[0]),
 			changed: true
@@ -9814,7 +9993,7 @@ var PgKnowledgePages = class {
 	}
 	async removePinAudience(input) {
 		return this.#tx(async (tx) => {
-			const existing = (await this.#rows(tx, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 FOR UPDATE`, [input.pageId]))[0];
+			const existing = (await this.#rows(tx, `SELECT * FROM ${this.#pins} WHERE "pageId" = $1 AND "kind" = $2 FOR UPDATE`, [input.pageId, input.kind ?? "page"]))[0];
 			if (!existing) return null;
 			const current = existing.audience ?? [];
 			const remaining = current.filter((entry) => !input.audience.includes(entry));
@@ -9846,6 +10025,7 @@ var PgKnowledgePages = class {
 			t.mentions,
 			t.stamps,
 			t.notes,
+			t.links,
 			t.pages
 		].map((name) => this.#q(name)).join(", ");
 		await this.#client.query(`TRUNCATE ${tables}`);
@@ -9864,9 +10044,10 @@ var PgKnowledgePages = class {
 		const params = new Params();
 		const where = [`p."deletedAt" IS NULL`, new ReadFilter(input.read, params, this.#pages).readable("s")];
 		if (input.audience !== "all") where.push(`pn."audience" && ${params.add(input.audience)}::text[]`);
+		if (input.kind) where.push(`pn."kind" = ${params.add(input.kind)}`);
 		if (input.pageIds) where.push(`pn."pageId" = ANY(${params.add(input.pageIds)}::text[])`);
-		if (input.excludePageIds?.length) where.push(`pn."pageId" <> ALL(${params.add(input.excludePageIds)}::text[])`);
-		if (input.withBody) where.push(`p."body" ~ '\\S'`);
+		if (input.excludePageIds?.length) where.push(`(pn."kind" <> 'page' OR pn."pageId" <> ALL(${params.add(input.excludePageIds)}::text[]))`);
+		if (input.withBody) where.push(`(pn."kind" <> 'page' OR p."body" ~ '\\S')`);
 		const from = `FROM ${this.#pins} pn JOIN ${this.#pages} p ON p."id" = pn."pageId" JOIN ${this.#pages} s ON s."id" = p."scopeId"`;
 		const totalWhere = where.join(" AND ");
 		if (input.cursor) {
@@ -9932,7 +10113,7 @@ async function pgKnowledgeSnapshot(db, schemaName) {
 }
 /** Drops exactly the Knowledge tables (never Memory's) and recreates schema 4. */
 async function resetPgKnowledgePagesSchema(client, schemaName) {
-	const tables = KNOWLEDGE_RESETTABLE_TABLE_NAMES.map((table) => qualify(schemaName, table)).join(", ");
+	const tables = [...KNOWLEDGE_RESETTABLE_TABLE_NAMES, PG_KNOWLEDGE_PAGES_TABLES.links].map((table) => qualify(schemaName, table)).join(", ");
 	await client.query(`DROP TABLE IF EXISTS ${tables} CASCADE`);
 	await initPgKnowledgePagesSchema(client, schemaName);
 }
@@ -10007,7 +10188,8 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 			...super.getCapabilities(),
 			schemaVersion: 4,
 			supportsSchemaInspection: true,
-			supportsExplicitReset: true
+			supportsExplicitReset: true,
+			supportsPinKinds: true
 		};
 	}
 	async init() {
@@ -10037,6 +10219,9 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 	listChildScopes(input) {
 		return this.#pages.listChildScopes(input);
 	}
+	countChildScopes(input) {
+		return this.#pages.countChildScopes(input);
+	}
 	getPages(input) {
 		return this.#pages.getPages(input);
 	}
@@ -10076,6 +10261,21 @@ var KnowledgePG = class extends _mastra_core_storage.KnowledgeStorage {
 	listNotes(input) {
 		return this.#pages.listNotes(input);
 	}
+	countChildPages(input) {
+		return this.#pages.countChildPages(input);
+	}
+	replacePageBodyLinks(input) {
+		return this.#pages.replacePageBodyLinks(input);
+	}
+	listPageBodyLinkSources(input) {
+		return this.#pages.listPageBodyLinkSources(input);
+	}
+	countPageLinks(input) {
+		return this.#pages.countPageLinks(input);
+	}
+	listPageLinks(input) {
+		return this.#pages.listPageLinks(input);
+	}
 	countNotes(input) {
 		return this.#pages.countNotes(input);
 	}
@@ -19025,6 +19225,8 @@ const timeToFirstTokenSortSupported = _mastra_core_storage.TRACE_QUERY_ORDER_FIE
 const spanQueryOutcomeFieldsSupported = "outcome" in (_mastra_core_storage.SPAN_QUERY_FIELD_REGISTRY ?? {});
 const traceQueryOutcomeFieldsSupported = "outcome" in (_mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {});
 const outcomeFeatures = [...spanQueryOutcomeFieldsSupported ? ["span-query-outcome-fields"] : [], ...traceQueryOutcomeFieldsSupported ? ["trace-query-outcome-fields"] : []];
+/** Core before the fields rejects their trace and span predicates, so the feature is only declared when core plans them. */
+const contextFieldFeatures = "requestId" in (_mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {}) ? ["trace-query-context-fields"] : [];
 const timingFeatures = [
 	...timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [],
 	...timeToFirstChunkSortSupported ? ["trace-query-time-to-first-chunk-sort"] : [],
@@ -19059,6 +19261,9 @@ const TRACE_FIELDS = {
 	sessionId: "r.\"sessionId\"",
 	userId: "r.\"userId\"",
 	organizationId: "r.\"organizationId\"",
+	requestId: "r.\"requestId\"",
+	serviceName: "r.\"serviceName\"",
+	experimentId: "r.\"experimentId\"",
 	startedAt: "r.\"startedAt\"",
 	endedAt: "r.\"endedAt\"",
 	durationMs: durationMsSql("r.\"startedAt\"", "r.\"endedAt\""),
@@ -19098,7 +19303,10 @@ const SPAN_FIELDS = {
 	runId: "s.\"runId\"",
 	sessionId: "s.\"sessionId\"",
 	userId: "s.\"userId\"",
-	organizationId: "s.\"organizationId\""
+	organizationId: "s.\"organizationId\"",
+	requestId: "s.\"requestId\"",
+	serviceName: "s.\"serviceName\"",
+	experimentId: "s.\"experimentId\""
 };
 const SPAN_QUERY_FIELDS = {
 	...SPAN_FIELDS,
@@ -19107,9 +19315,6 @@ const SPAN_QUERY_FIELDS = {
 	parentSpanId: "s.\"parentSpanId\"",
 	threadId: "s.\"threadId\"",
 	resourceId: "s.\"resourceId\"",
-	requestId: "s.\"requestId\"",
-	serviceName: "s.\"serviceName\"",
-	experimentId: "s.\"experimentId\"",
 	environment: "s.\"environment\"",
 	executionSource: "s.\"executionSource\"",
 	parentEntityType: "s.\"parentEntityType\"",
@@ -19373,6 +19578,9 @@ const ROOT_PUSHDOWN_FIELDS = /* @__PURE__ */ new Set([
 	"sessionId",
 	"userId",
 	"organizationId",
+	"requestId",
+	"serviceName",
+	"experimentId",
 	"startedAt",
 	"endedAt",
 	"entityId",
@@ -19544,7 +19752,10 @@ function compilePostgresTraceScope(schema, selection, relationCollections, scope
       s."runId",
       s."sessionId",
       s."userId",
-      s."organizationId"
+      s."organizationId",
+      s."requestId",
+      s."serviceName",
+      s."experimentId"
     FROM ${spanTable} s
     WHERE s."traceId" IS NOT NULL
       AND s."traceId" IN (SELECT "traceId" FROM root_scope)
@@ -21811,6 +22022,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
+			...contextFieldFeatures,
 			...timingFeatures,
 			...outcomeFeatures,
 			"trace-query-root-span-fields",
@@ -21838,6 +22050,7 @@ var ObservabilityStoragePostgresVNext = class ObservabilityStoragePostgresVNext
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
+			...contextFieldFeatures,
 			...timingFeatures,
 			...outcomeFeatures,
 			"trace-query-root-span-fields",