@mastra/libsql 1.29.0-alpha.1 → 1.29.0

package/dist/index.cjs

@@ -6650,7 +6650,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 : {};
@@ -6671,16 +6672,18 @@ function createKnowledgePagesCoreLoader(features, loadStorageModule) {
 	};
 }
 /**
-* Keyword-search words: the query split on whitespace, lowercased, deduplicated. A hit needs at
-* least one of them (as a case-insensitive substring); 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. Pages rank by how many query words they match first; these points only
-* break ties between pages that match the same number of words.
+* 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,
@@ -6706,9 +6709,37 @@ const KNOWLEDGE_PAGE_TABLES = {
 	mentions: "mastra_knowledge_mentions",
 	pins: "mastra_knowledge_pins",
 	pinAudiences: "mastra_knowledge_pin_audiences",
-	activity: "mastra_knowledge_activity"
+	activity: "mastra_knowledge_activity",
+	links: "mastra_knowledge_page_links"
 };
 const T = KNOWLEDGE_PAGE_TABLES;
+function pinsTableDDL(name) {
+	return `CREATE TABLE IF NOT EXISTS "${name}" (
+    id TEXT PRIMARY KEY,
+    pageId TEXT NOT NULL,
+    kind TEXT NOT NULL DEFAULT 'page',
+    depth INTEGER,
+    audience TEXT NOT NULL,
+    createdBy TEXT NOT NULL,
+    createdAt TEXT NOT NULL,
+    updatedAt TEXT NOT NULL,
+    UNIQUE (pageId, kind)
+  )`;
+}
+/**
+* Pins tables from before pin kinds kept one pin per page (`pageId UNIQUE`). SQLite can't drop that
+* constraint in place, so the table is rebuilt with every existing pin as a `page` pin. Run after
+* {@link KNOWLEDGE_PAGE_DDL}, in the same transaction; a no-op once `kind` exists.
+*/
+async function upgradeKnowledgePinKinds(tx) {
+	if ((await tx.execute(`SELECT name FROM pragma_table_info('${T.pins}')`)).rows.some((row) => String(row.name) === "kind")) return;
+	const next = `${T.pins}_kinds`;
+	await tx.execute(`DROP TABLE IF EXISTS "${next}"`);
+	await tx.execute(pinsTableDDL(next));
+	await tx.execute(`INSERT INTO "${next}" (id, pageId, kind, audience, createdBy, createdAt, updatedAt) SELECT id, pageId, 'page', audience, createdBy, createdAt, updatedAt FROM "${T.pins}"`);
+	await tx.execute(`DROP TABLE "${T.pins}"`);
+	await tx.execute(`ALTER TABLE "${next}" RENAME TO "${T.pins}"`);
+}
 /** DDL for the schema-4 page tables, in creation order. Every statement is idempotent. */
 const KNOWLEDGE_PAGE_DDL = [
 	`CREATE TABLE IF NOT EXISTS "mastra_knowledge_access_state" (
@@ -6772,14 +6803,7 @@ const KNOWLEDGE_PAGE_DDL = [
     PRIMARY KEY (noteId, pageId)
   )`,
 	`CREATE INDEX IF NOT EXISTS idx_kmentions_page ON "${T.mentions}" (pageId)`,
-	`CREATE TABLE IF NOT EXISTS "${T.pins}" (
-    id TEXT PRIMARY KEY,
-    pageId TEXT NOT NULL UNIQUE,
-    audience TEXT NOT NULL,
-    createdBy TEXT NOT NULL,
-    createdAt TEXT NOT NULL,
-    updatedAt TEXT NOT NULL
-  )`,
+	pinsTableDDL(T.pins),
 	`CREATE TABLE IF NOT EXISTS "${T.pinAudiences}" (
     pinId TEXT NOT NULL,
     audience TEXT NOT NULL,
@@ -6796,7 +6820,16 @@ const KNOWLEDGE_PAGE_DDL = [
     provenance TEXT NOT NULL,
     createdAt TEXT NOT NULL
   )`,
-	`CREATE INDEX IF NOT EXISTS idx_kactivity_page ON "${T.activity}" (pageId, id DESC)`
+	`CREATE INDEX IF NOT EXISTS idx_kactivity_page ON "${T.activity}" (pageId, id DESC)`,
+	`CREATE TABLE IF NOT EXISTS "${T.links}" (
+    fromPageId TEXT NOT NULL,
+    ref TEXT NOT NULL,
+    toPageId TEXT,
+    count INTEGER NOT NULL,
+    PRIMARY KEY (fromPageId, ref)
+  ) WITHOUT ROWID`,
+	`CREATE INDEX IF NOT EXISTS idx_klinks_to ON "${T.links}" (toPageId) WHERE toPageId IS NOT NULL`,
+	`CREATE INDEX IF NOT EXISTS idx_klinks_ref ON "${T.links}" (ref) WHERE toPageId IS NULL`
 ];
 function str(value) {
 	return value === null || value === void 0 ? void 0 : String(value);
@@ -6851,6 +6884,8 @@ function toPin(row) {
 	return {
 		id: String(row.id),
 		pageId: String(row.pageId),
+		kind: String(row.kind),
+		...row.depth !== null && row.depth !== void 0 ? { depth: Number(row.depth) } : {},
 		audience: JSON.parse(String(row.audience)),
 		createdBy: String(row.createdBy),
 		createdAt: new Date(String(row.createdAt)),
@@ -6979,10 +7014,11 @@ var LibSQLKnowledgePages = class {
 		this.#read = config.read;
 		this.#transaction = config.transaction;
 	}
-	/** Deletes every row from the page tables (scopes, pages, notes, pins, activity). */
+	/** Deletes every row from the page tables (scopes, pages, notes, pins, activity, links). */
 	async clearAll() {
 		await this.#transaction(async (tx) => {
 			for (const table of [
+				T.links,
 				T.activity,
 				T.pinAudiences,
 				T.pins,
@@ -7164,13 +7200,19 @@ var LibSQLKnowledgePages = class {
 		const limit = limitOf(input.limit, core.MAX_KNOWLEDGE_PAGE_LIST_LIMIT);
 		const cursor = decodeCursor(input.cursor, 2);
 		const args = [input.parentId];
+		let filter = "";
+		if (input.read) {
+			const readable = readableScopes(input.read);
+			filter = ` AND id IN (${readable.sql})`;
+			args.push(...readable.args);
+		}
 		let after = "";
 		if (cursor) {
 			after = ` AND (position > ? OR (position = ? AND id > ?))`;
 			args.push(cursor[0], cursor[0], cursor[1]);
 		}
 		args.push(limit + 1);
-		const rows = await this.#query(this.#read, `SELECT * FROM "${T.pages}" WHERE isScope = 1 AND parentId IS ?${after} ORDER BY position, id LIMIT ?`, args);
+		const rows = await this.#query(this.#read, `SELECT * FROM "${T.pages}" WHERE isScope = 1 AND parentId IS ?${filter}${after} ORDER BY position, id LIMIT ?`, args);
 		return this.#pageOutput(rows, limit, (row) => [String(row.position), String(row.id)]);
 	}
 	#pageOutput(rows, limit, cursorOf) {
@@ -7455,9 +7497,8 @@ var LibSQLKnowledgePages = class {
 				args: [input.sourceId]
 			});
 			const pins = await this.#query(tx, `SELECT * FROM "${T.pins}" WHERE pageId IN (?, ?)`, [input.sourceId, input.targetId]);
-			const sourcePin = pins.find((pin) => String(pin.pageId) === input.sourceId);
-			if (sourcePin) {
-				const targetPin = pins.find((pin) => String(pin.pageId) === input.targetId);
+			for (const sourcePin of pins.filter((pin) => String(pin.pageId) === input.sourceId)) {
+				const targetPin = pins.find((pin) => String(pin.pageId) === input.targetId && pin.kind === sourcePin.kind);
 				const audience = JSON.parse(String(sourcePin.audience));
 				if (targetPin) {
 					const merged = [.../* @__PURE__ */ new Set([...JSON.parse(String(targetPin.audience)), ...audience])];
@@ -7557,6 +7598,15 @@ var LibSQLKnowledgePages = class {
 		const rows = await this.#query(this.#read, `SELECT n.* FROM "${T.notes}" n WHERE n.pageId = ?${input.includeDeleted ? "" : " AND n.deletedAt IS NULL"} AND ${readable.sql}${after} ORDER BY n.createdAt, n.id LIMIT ?`, args);
 		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 === 0) return counts;
+		const readable = readableScopes(input.read);
+		const rows = await this.#query(this.#read, `SELECT parentId, COUNT(*) AS total FROM "${T.pages}" WHERE parentId IN (SELECT value FROM json_each(?)) AND isScope = 1 AND id IN (${readable.sql}) GROUP BY parentId`, [jsonList(ids), ...readable.args]);
+		for (const row of rows) counts[String(row.parentId)] = Number(row.total);
+		return counts;
+	}
 	async countChildPages(input) {
 		const ids = [...new Set(input.parentIds)];
 		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
@@ -7566,6 +7616,111 @@ var LibSQLKnowledgePages = class {
 		for (const row of rows) counts[String(row.parentId)] = Number(row.total);
 		return counts;
 	}
+	async replacePageBodyLinks(input) {
+		await this.#transaction(async (tx) => {
+			await tx.execute({
+				sql: `DELETE FROM "${T.links}" WHERE fromPageId = ?`,
+				args: [input.pageId]
+			});
+			if (input.links.length === 0) return;
+			await tx.execute({
+				sql: `INSERT INTO "${T.links}" (fromPageId, ref, toPageId, count) SELECT ?, json_extract(value, '$.ref'), json_extract(value, '$.toPageId'), json_extract(value, '$.count') FROM json_each(?)`,
+				args: [input.pageId, JSON.stringify(input.links.map(({ ref, toPageId, count }) => ({
+					ref,
+					toPageId,
+					count
+				})))]
+			});
+		});
+	}
+	async listPageBodyLinkSources(input) {
+		const refs = input.refs ?? [];
+		const targets = input.toPageIds ?? [];
+		if (refs.length === 0 && targets.length === 0) return [];
+		return (await this.#query(this.#read, `SELECT DISTINCT fromPageId FROM "${T.links}" WHERE (toPageId IS NULL AND ref IN (SELECT value FROM json_each(?))) OR toPageId IN (SELECT value FROM json_each(?)) ORDER BY fromPageId`, [jsonList(refs), jsonList(targets)])).map((row) => String(row.fromPageId));
+	}
+	/**
+	* Visible links touching `ids` (from them for `out`, to them for `in`): resolved, both ends live
+	* and readable, not self-links; a note link also needs a visible live note. One row per
+	* (from, to, kind), counts summed.
+	*/
+	async #links(read, kinds, ids, direction) {
+		const wanted = new Set(kinds ?? ["body", "note"]);
+		const touches = (from, to) => {
+			const parts = [];
+			const args = [];
+			if (direction !== "in") {
+				parts.push(`${from} IN (SELECT value FROM json_each(?))`);
+				args.push(jsonList(ids));
+			}
+			if (direction !== "out") {
+				parts.push(`${to} IN (SELECT value FROM json_each(?))`);
+				args.push(jsonList(ids));
+			}
+			return {
+				sql: `(${parts.join(" OR ")})`,
+				args
+			};
+		};
+		const sources = [];
+		const args = [];
+		if (wanted.has("body")) {
+			const near = touches("l.fromPageId", "l.toPageId");
+			sources.push(`SELECT l.fromPageId AS fromPageId, l.toPageId AS toPageId, 'body' AS kind, l.count AS count FROM "${T.links}" l WHERE l.toPageId IS NOT NULL AND ${near.sql}`);
+			args.push(...near.args);
+		}
+		if (wanted.has("note")) {
+			const near = touches("n.pageId", "m.pageId");
+			const visible = noteReadable("n", read);
+			sources.push(`SELECT n.pageId AS fromPageId, m.pageId AS toPageId, 'note' AS kind, 1 AS count FROM "${T.mentions}" m JOIN "${T.notes}" n ON n.id = m.noteId WHERE n.deletedAt IS NULL AND ${near.sql} AND ${visible.sql}`);
+			args.push(...near.args, ...visible.args);
+		}
+		if (sources.length === 0) return [];
+		const fromReadable = pageReadable("fp", read);
+		const toReadable = pageReadable("tp", read);
+		return this.#query(this.#read, `SELECT e.fromPageId AS fromPageId, e.toPageId AS toPageId, e.kind AS kind, SUM(e.count) AS count
+        FROM (${sources.join(" UNION ALL ")}) e
+        JOIN "${T.pages}" fp ON fp.id = e.fromPageId AND fp.deletedAt IS NULL AND ${fromReadable.sql}
+        JOIN "${T.pages}" tp ON tp.id = e.toPageId AND tp.deletedAt IS NULL AND ${toReadable.sql}
+        WHERE e.fromPageId <> e.toPageId
+        GROUP BY e.fromPageId, e.toPageId, e.kind
+        ORDER BY e.fromPageId, e.toPageId, CASE e.kind WHEN 'body' THEN 0 ELSE 1 END`, [
+			...args,
+			...fromReadable.args,
+			...toReadable.args
+		]);
+	}
+	async countPageLinks(input) {
+		const ids = [...new Set(input.pageIds)];
+		const linked = new Map(ids.map((id) => [id, {
+			in: /* @__PURE__ */ new Set(),
+			out: /* @__PURE__ */ new Set()
+		}]));
+		if (ids.length === 0) return {};
+		for (const row of await this.#links(input.read, input.kinds, ids, "both")) {
+			const from = String(row.fromPageId);
+			const to = String(row.toPageId);
+			linked.get(from)?.out.add(to);
+			linked.get(to)?.in.add(from);
+		}
+		return Object.fromEntries([...linked].map(([id, sets]) => [id, {
+			in: sets.in.size,
+			out: sets.out.size
+		}]));
+	}
+	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 ids = [...new Set(input.pageIds)];
+		if (ids.length === 0) return [];
+		const core = await loadPagesCore();
+		return (await this.#links(input.read, input.kinds, ids, input.direction ?? "both")).slice(0, Math.min(limit, core.MAX_KNOWLEDGE_PAGE_LINKS)).map((row) => ({
+			fromPageId: String(row.fromPageId),
+			toPageId: String(row.toPageId),
+			kind: row.kind === "note" ? "note" : "body",
+			count: Number(row.count)
+		}));
+	}
 	async countNotes(input) {
 		const ids = [...new Set(input.pageIds)];
 		const counts = Object.fromEntries(ids.map((id) => [id, 0]));
@@ -7827,17 +7982,21 @@ var LibSQLKnowledgePages = class {
 		});
 	}
 	addPinAudience(input) {
+		const kind = input.kind ?? "page";
+		const depth = kind === "list" ? input.depth ?? 1 : null;
 		return this.#transaction(async (tx) => {
 			const page = await this.#livePage(tx, input.pageId);
 			const now = (/* @__PURE__ */ new Date()).toISOString();
-			const existing = (await this.#query(tx, `SELECT * FROM "${T.pins}" WHERE pageId = ?`, [input.pageId]))[0];
+			const existing = (await this.#query(tx, `SELECT * FROM "${T.pins}" WHERE pageId = ? AND kind = ?`, [input.pageId, kind]))[0];
 			if (!existing) {
 				const id = (0, _mastra_core_storage.createKnowledgeUlid)();
 				await tx.execute({
-					sql: `INSERT INTO "${T.pins}" (id, pageId, audience, createdBy, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, ?)`,
+					sql: `INSERT INTO "${T.pins}" (id, pageId, kind, depth, audience, createdBy, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
 					args: [
 						id,
 						input.pageId,
+						kind,
+						depth,
 						JSON.stringify([...new Set(input.audience)]),
 						input.createdBy,
 						now,
@@ -7854,11 +8013,13 @@ var LibSQLKnowledgePages = class {
 			}
 			const current = JSON.parse(String(existing.audience));
 			const merged = [.../* @__PURE__ */ new Set([...current, ...input.audience])];
-			if (merged.length !== current.length) {
+			const depthChanged = (existing.depth === null ? null : Number(existing.depth)) !== depth;
+			if (merged.length !== current.length || depthChanged) {
 				await tx.execute({
-					sql: `UPDATE "${T.pins}" SET audience = ?, updatedAt = ? WHERE id = ?`,
+					sql: `UPDATE "${T.pins}" SET audience = ?, depth = ?, updatedAt = ? WHERE id = ?`,
 					args: [
 						JSON.stringify(merged),
+						depth,
 						now,
 						String(existing.id)
 					]
@@ -7875,7 +8036,7 @@ var LibSQLKnowledgePages = class {
 	}
 	removePinAudience(input) {
 		return this.#transaction(async (tx) => {
-			const existing = (await this.#query(tx, `SELECT * FROM "${T.pins}" WHERE pageId = ?`, [input.pageId]))[0];
+			const existing = (await this.#query(tx, `SELECT * FROM "${T.pins}" WHERE pageId = ? AND kind = ?`, [input.pageId, input.kind ?? "page"]))[0];
 			if (!existing) return null;
 			const current = JSON.parse(String(existing.audience));
 			const remove = new Set(input.audience);
@@ -7919,15 +8080,19 @@ var LibSQLKnowledgePages = class {
 			filters += ` AND pin.id IN (SELECT pa.pinId FROM json_each(?) a JOIN "${T.pinAudiences}" pa ON pa.audience = a.value)`;
 			args.push(jsonList(input.audience));
 		}
+		if (input.kind) {
+			filters += ` AND pin.kind = ?`;
+			args.push(input.kind);
+		}
 		if (input.pageIds) {
 			filters += ` AND pin.pageId IN (SELECT value FROM json_each(?))`;
 			args.push(jsonList(input.pageIds));
 		}
 		if (input.excludePageIds?.length) {
-			filters += ` AND pin.pageId NOT IN (SELECT value FROM json_each(?))`;
+			filters += ` AND (pin.kind <> 'page' OR pin.pageId NOT IN (SELECT value FROM json_each(?)))`;
 			args.push(jsonList(input.excludePageIds));
 		}
-		if (input.withBody) filters += ` AND p.body IS NOT NULL AND trim(p.body, char(32, 9, 10, 11, 12, 13)) <> ''`;
+		if (input.withBody) filters += ` AND (pin.kind <> 'page' OR (p.body IS NOT NULL AND trim(p.body, char(32, 9, 10, 11, 12, 13)) <> ''))`;
 		const from = `FROM "${T.pins}" pin JOIN "${T.pages}" p ON p.id = pin.pageId WHERE p.deletedAt IS NULL AND ${readable.sql}${filters}`;
 		let total;
 		if (input.count) total = Number((await this.#query(this.#read, `SELECT COUNT(*) AS n ${from}`, args))[0].n);
@@ -7999,7 +8164,8 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			contractVersion: 4,
 			schemaVersion: 4,
 			supportsSchemaInspection: true,
-			supportsExplicitReset: true
+			supportsExplicitReset: true,
+			supportsPinKinds: true
 		};
 	}
 	async dangerouslyClearAll() {
@@ -8029,6 +8195,7 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 			const inspection = await this.#inspectPages(tx);
 			if (inspection.status === "incompatible-reset-required") throw new _mastra_core_storage.KnowledgeSchemaResetRequiredError(inspection);
 			for (const statement of KNOWLEDGE_PAGE_DDL) await tx.execute(statement);
+			await upgradeKnowledgePinKinds(tx);
 			await tx.execute({
 				sql: `INSERT OR IGNORE INTO "${TABLE_KNOWLEDGE_PAGES_STATE}" (id, schemaVersion) VALUES ('knowledge', ?)`,
 				args: [4]
@@ -8037,7 +8204,11 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 	}
 	async dangerouslyReset() {
 		await withClientWriteLock(this.#client, async () => {
-			await this.#client.batch([...KNOWLEDGE_RESETTABLE_TABLE_NAMES, KNOWLEDGE_PAGE_TABLES.pinAudiences].map((table) => ({
+			await this.#client.batch([
+				...KNOWLEDGE_RESETTABLE_TABLE_NAMES,
+				KNOWLEDGE_PAGE_TABLES.pinAudiences,
+				KNOWLEDGE_PAGE_TABLES.links
+			].map((table) => ({
 				sql: `DROP TABLE IF EXISTS "${table}"`,
 				args: []
 			})), "write");
@@ -8059,6 +8230,9 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 	listChildScopes(input) {
 		return this.#pages.listChildScopes(input);
 	}
+	countChildScopes(input) {
+		return this.#pages.countChildScopes(input);
+	}
 	getPage(input) {
 		return this.#pages.getPage(input);
 	}
@@ -8098,6 +8272,18 @@ var KnowledgeLibSQL = class extends _mastra_core_storage.KnowledgeStorage {
 	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);
 	}