@mastra/code-sdk 1.17.0 → 1.18.0-alpha.0

package/dist/knowledge-inspector.js

@@ -1,5 +1,6 @@
-import { resolveKnowledgeScopeIdentity } from "./knowledge-scope.js";
-import { createKnowledgeNodeCursor, isKnowledgeScopeVisible, parseKnowledgeWikilinks } from "@mastra/core/storage";
+import { knowledgeSessionTags, resolveKnowledgeSessionScopes } from "./knowledge-scope.js";
+import { knowledgeScopeAddress } from "@mastra/core/knowledge";
+import { parseKnowledgeWikilinks } from "@mastra/core/storage";
 // src/knowledge-inspector.ts
 var KnowledgeInspectorError = class extends Error {
 	code;
@@ -11,17 +12,16 @@ var KnowledgeInspectorError = class extends Error {
 };
 const HANDLE_TTL_MS = 3e5;
 const MAX_OPAQUE_ENTRIES = 1e3;
-const DEFAULT_RECORD_LIMIT = 50;
-const MAX_RECORD_LIMIT = 50;
-const DEFAULT_FACT_LIMIT = 25;
-const MAX_FACT_LIMIT = 100;
+const DEFAULT_PAGE_LIMIT = 50;
+const MAX_PAGE_LIMIT = 50;
+const DEFAULT_NOTE_LIMIT = 25;
+const MAX_NOTE_LIMIT = 100;
 const DEFAULT_ACTIVITY_LIMIT = 20;
 const MAX_ACTIVITY_LIMIT = 100;
-const MAX_RELATED_RECORDS = 25;
+const MAX_RELATED_PAGES = 25;
 const MAX_RANK_CANDIDATES = 50;
-const MAX_RANK_FACTS = 100;
-const RRF_K = 60;
-const MAX_NODE_CONTENT_BYTES = 32768;
+const MAX_RANK_NOTES = 100;
+const MAX_BODY_BYTES = 32768;
 function opaqueToken() {
 	return Buffer.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(24))).toString("base64url");
 }
@@ -30,24 +30,22 @@ function boundedLimit(value, fallback, maximum) {
 	if (!Number.isInteger(value) || value < 1) return fallback;
 	return Math.min(value, maximum);
 }
-function scopeBadge(scope) {
-	const entry = scope.at(-1);
-	if (!entry) throw new KnowledgeInspectorError("unavailable", "Knowledge record has no scope.");
-	const separator = entry.indexOf(":");
-	return {
-		level: entry.slice(0, separator),
-		id: entry.slice(separator + 1)
+function badgeOf(address) {
+	if (!address) return {
+		level: "unknown",
+		id: ""
 	};
-}
-function knowledgeSummary(record) {
+	const separator = address.indexOf(":");
 	return {
-		text: record.text,
-		scope: scopeBadge(record.scope),
-		sourceThreadId: record.sourceThreadId,
-		capturedAt: record.capturedAt.toISOString(),
-		when: record.when?.toISOString()
+		level: address.slice(0, separator),
+		id: address.slice(separator + 1)
 	};
 }
+/** A session tag in Knowledge's canonical form; every type the session holds has one `$param`. */
+function canonical(tag) {
+	const separator = tag.indexOf(":");
+	return knowledgeScopeAddress(`${tag.slice(0, separator)}:$value`, { value: tag.slice(separator + 1) });
+}
 function truncateUtf8(value, maxBytes) {
 	const encoded = Buffer.from(value);
 	if (encoded.byteLength <= maxBytes) return {
@@ -62,18 +60,28 @@ function truncateUtf8(value, maxBytes) {
 		truncated: true
 	};
 }
+/**
+* The /knowledge inspector: reads the pages and notes a session's code agent can read, one level at a
+* time (the session's shared tags, then its project resource, then its thread), through the same
+* Knowledge access rules the agent's runs use.
+*/
 var ScopedKnowledgeInspector = class {
 	#knowledge;
+	#store;
 	#session;
 	#handles = /* @__PURE__ */ new Map();
 	#cursors = /* @__PURE__ */ new Map();
+	#scopeAddresses = /* @__PURE__ */ new Map();
 	#fingerprint;
 	#identityKey = opaqueToken();
+	#hostScopes;
 	constructor(input) {
 		this.#knowledge = input.knowledge;
+		this.#store = input.store;
 		this.#session = input.session;
+		this.#hostScopes = input.hostScopes ?? [];
 		this.#session.subscribe((event) => {
-			if (event.type === "thread_changed" || event.type === "thread_created" || event.type === "thread_deleted") this.#invalidateIdnode();
+			if (event.type === "thread_changed" || event.type === "thread_created" || event.type === "thread_deleted") this.#invalidate();
 		});
 	}
 	async getScopeTree() {
@@ -84,7 +92,7 @@ var ScopedKnowledgeInspector = class {
 			roots: [
 				{
 					level: "org",
-					id: binding.organizationId,
+					id: binding.sessionTags.join(" + "),
 					available: true
 				},
 				{
@@ -106,57 +114,46 @@ var ScopedKnowledgeInspector = class {
 	}
 	async listNodes(input) {
 		const binding = await this.#binding();
-		const scope = this.#scope(binding, input.level);
-		const limit = boundedLimit(input.limit, DEFAULT_RECORD_LIMIT, MAX_RECORD_LIMIT);
-		const sort = input.sort ?? "relevant";
-		if (sort === "recent") {
-			const cursor = this.#consumeCursor(input.cursor, binding, input.level, "node", {
-				namePrefix: input.namePrefix,
-				kind: input.kind,
-				sort
-			});
-			const records = await this.#knowledge.listNodes({
-				scope,
+		const view = await this.#view(binding, input.level);
+		const limit = boundedLimit(input.limit, DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT);
+		const sort = input.sort ?? "name";
+		const filters = {
+			namePrefix: input.namePrefix,
+			sort
+		};
+		if (sort === "name") {
+			const cursor = this.#consumeCursor(input.cursor, binding, input.level, "node", filters);
+			const result = await this.#store.listPages({
+				read: view.read,
 				namePrefix: input.namePrefix,
-				kind: input.kind,
 				cursor,
 				limit
 			});
-			const nodes = await Promise.all(records.map(async (record) => ({
-				...this.#recordSummary(record, binding, input.level),
-				relationshipCounts: (await this.#sampledRelationshipCounts(record, scope)).counts
+			const nodes = await Promise.all(result.pages.map(async (page) => ({
+				...await this.#summary(page, binding, view),
+				relationshipCounts: await this.#counts(page, view)
 			})));
 			await this.#assertStable(binding);
 			return {
 				identityKey: binding.identityKey,
 				scopeLevel: input.level,
 				nodes,
-				nextCursor: records.length === limit ? this.#mintCursor(binding, input.level, "node", createKnowledgeNodeCursor(records.at(-1), {
-					namePrefix: input.namePrefix,
-					kind: input.kind
-				}), {
-					namePrefix: input.namePrefix,
-					kind: input.kind,
-					sort
-				}) : void 0,
+				nextCursor: result.nextCursor ? this.#mintCursor(binding, input.level, "node", result.nextCursor, filters) : void 0,
 				sort,
 				coverage: "exact"
 			};
 		}
-		const filters = {
-			namePrefix: input.namePrefix,
-			kind: input.kind,
-			sort
-		};
-		const encodedSnapshot = this.#consumeCursor(input.cursor, binding, input.level, "ranked-node", filters);
-		const snapshot = encodedSnapshot ? JSON.parse(encodedSnapshot) : await this.#rankedNodeSnapshot(scope, input.namePrefix, input.kind, sort);
-		const page = snapshot.entries.slice(snapshot.offset, snapshot.offset + limit);
+		const encoded = this.#consumeCursor(input.cursor, binding, input.level, "ranked-node", filters);
+		const snapshot = encoded ? JSON.parse(encoded) : await this.#ranked(view, input.namePrefix);
 		const nodes = [];
-		for (const entry of page) {
-			const node = await this.#knowledge.getNode(entry.id);
-			if (!node || !isKnowledgeScopeVisible(node.scope, scope)) continue;
+		for (const entry of snapshot.entries.slice(snapshot.offset, snapshot.offset + limit)) {
+			const page = await this.#store.getPage({
+				id: entry.id,
+				read: view.read
+			});
+			if (!page || page.deletedAt) continue;
 			nodes.push({
-				...this.#recordSummary(node, binding, input.level),
+				...await this.#summary(page, binding, view),
 				relationshipCounts: entry.counts
 			});
 		}
@@ -171,116 +168,111 @@ var ScopedKnowledgeInspector = class {
 				offset: nextOffset
 			}), filters) : void 0,
 			sort,
-			coverage: "recent-window"
+			coverage: "window"
 		};
 	}
 	async getNode(input) {
 		const binding = await this.#binding();
 		const handle = this.#readHandle(input.handle, binding, "node");
-		const scope = this.#scope(binding, handle.level);
-		const node = await this.#knowledge.getNode(handle.recordId);
-		this.#assertVisible(node, scope);
-		const limit = boundedLimit(input.recordLimit, DEFAULT_FACT_LIMIT, MAX_FACT_LIMIT);
-		const recordsAfter = this.#consumeCursor(input.recordsCursor, binding, handle.level, "records");
+		const view = await this.#view(binding, handle.level);
+		const page = await this.#store.getPage({
+			id: handle.recordId,
+			read: view.read
+		});
+		if (!page || page.deletedAt) throw new KnowledgeInspectorError("not-visible", "Knowledge page is not visible in the selected scope.");
+		const limit = boundedLimit(input.recordLimit, DEFAULT_NOTE_LIMIT, MAX_NOTE_LIMIT);
+		const notesAfter = this.#consumeCursor(input.recordsCursor, binding, handle.level, "records");
 		const mentioningAfter = this.#consumeCursor(input.mentioningRecordsCursor, binding, handle.level, "mentioning-records");
-		const [recordsResult, mentioningResult] = await Promise.all([this.#knowledge.listKnowledgeAbout({
-			node: node.id,
-			scope,
-			after: recordsAfter,
+		const [notes, mentioning] = await Promise.all([this.#store.listNotes({
+			pageId: page.id,
+			read: view.read,
+			cursor: notesAfter,
 			limit
-		}), this.#knowledge.listKnowledgeMentioning({
-			node: node.id,
-			scope,
-			after: mentioningAfter,
+		}), this.#store.listNotesMentioning({
+			pageId: page.id,
+			read: view.read,
+			cursor: mentioningAfter,
 			limit
 		})]);
-		const mentioningRecords = mentioningResult.records.filter((record) => record.node !== node.id);
-		const content = truncateUtf8(node.content ?? "", MAX_NODE_CONTENT_BYTES);
-		const [outgoingTargets, incomingParents, relationship] = await Promise.all([
-			this.#outgoingTargets(node, recordsResult.records, scope, binding, handle.level),
-			this.#incomingParents(node, mentioningRecords, scope, binding, handle.level),
-			this.#sampledRelationshipCounts(node, scope)
+		const body = truncateUtf8(page.body ?? "", MAX_BODY_BYTES);
+		const [outgoing, incoming, counts] = await Promise.all([
+			this.#outgoing(page, notes.notes, view),
+			this.#incoming(mentioning.notes, view),
+			this.#counts(page, view)
 		]);
-		const links = await Promise.all(parseKnowledgeWikilinks(content.value).slice(0, MAX_RELATED_RECORDS).map(async (label) => {
-			const target = await this.#knowledge.resolveNode({
+		const links = await Promise.all(parseKnowledgeWikilinks(body.value).slice(0, MAX_RELATED_PAGES).map(async (label) => {
+			const [target] = await this.#store.findPagesByName({
 				name: label,
-				scope
+				read: view.read,
+				limit: 1
 			});
 			return {
 				label,
-				node: target ? this.#recordSummary(target, binding, handle.level) : void 0
+				node: target ? await this.#summary(target, binding, view) : void 0
 			};
 		}));
-		await this.#assertStable(binding);
-		return {
+		const summaries = (pages) => Promise.all(pages.map((related) => this.#summary(related, binding, view)));
+		const detail = {
 			identityKey: binding.identityKey,
 			scopeLevel: handle.level,
 			node: {
-				...this.#recordSummary(node, binding, handle.level),
-				relationshipCounts: relationship.counts
+				...await this.#summary(page, binding, view),
+				relationshipCounts: counts
 			},
-			records: recordsResult.records.map(knowledgeSummary),
-			recordsNextCursor: recordsResult.nextCursor ? this.#mintCursor(binding, handle.level, "records", recordsResult.nextCursor) : void 0,
-			mentioningRecords: mentioningRecords.map(knowledgeSummary),
-			mentioningRecordsNextCursor: mentioningResult.nextCursor ? this.#mintCursor(binding, handle.level, "mentioning-records", mentioningResult.nextCursor) : void 0,
+			records: await Promise.all(notes.notes.map((note) => this.#noteSummary(note))),
+			recordsNextCursor: notes.nextCursor ? this.#mintCursor(binding, handle.level, "records", notes.nextCursor) : void 0,
+			mentioningRecords: await Promise.all(mentioning.notes.map((note) => this.#noteSummary(note))),
+			mentioningRecordsNextCursor: mentioning.nextCursor ? this.#mintCursor(binding, handle.level, "mentioning-records", mentioning.nextCursor) : void 0,
 			outgoingTargets: {
-				nodes: outgoingTargets.nodes,
-				partial: outgoingTargets.partial || Boolean(recordsResult.nextCursor)
+				nodes: await summaries(outgoing.pages),
+				partial: outgoing.truncated || Boolean(notes.nextCursor)
 			},
 			incomingParents: {
-				nodes: incomingParents.nodes,
-				partial: incomingParents.partial || Boolean(mentioningResult.nextCursor)
+				nodes: await summaries(incoming.pages),
+				partial: incoming.truncated || Boolean(mentioning.nextCursor)
 			},
-			relationshipCounts: relationship.counts,
-			content: node.content === void 0 ? void 0 : content.value,
-			contentTruncated: content.truncated,
+			relationshipCounts: counts,
+			content: page.body === void 0 ? void 0 : body.value,
+			contentTruncated: body.truncated,
 			links
 		};
+		await this.#assertStable(binding);
+		return detail;
 	}
 	async listActivity(input) {
 		const binding = await this.#binding();
-		const scope = this.#scope(binding, input.level);
+		const view = await this.#view(binding, input.level);
 		const limit = boundedLimit(input.limit, DEFAULT_ACTIVITY_LIMIT, MAX_ACTIVITY_LIMIT);
-		const after = this.#consumeCursor(input.cursor, binding, input.level, "activity");
-		const events = await this.#knowledge.listActivity({
-			scope,
-			after,
+		const cursor = this.#consumeCursor(input.cursor, binding, input.level, "activity");
+		const result = await this.#store.listPageActivity({
+			read: view.read,
+			cursor,
 			limit
 		});
-		const activityEvents = [];
-		for (const event of events) {
-			const record = await this.#activityRecord(event, scope, binding, input.level);
-			activityEvents.push({
-				action: event.action,
-				recordType: event.recordType,
-				scope: scopeBadge(event.scope),
-				sourceThreadId: record ? event.sourceThreadId : void 0,
-				createdAt: event.createdAt.toISOString(),
-				record
-			});
-		}
+		const events = [];
+		for (const event of result.events) events.push(await this.#activityEvent(event, binding, view));
 		await this.#assertStable(binding);
 		return {
 			identityKey: binding.identityKey,
 			scopeLevel: input.level,
-			events: activityEvents,
-			nextCursor: events.length === limit ? this.#mintCursor(binding, input.level, "activity", events.at(-1).id) : void 0
+			events,
+			nextCursor: result.nextCursor ? this.#mintCursor(binding, input.level, "activity", result.nextCursor) : void 0
 		};
 	}
 	async #binding() {
-		const identity = resolveKnowledgeScopeIdentity(this.#session.state.get());
+		const session = resolveKnowledgeSessionScopes(this.#session.state.get(), this.#hostScopes);
 		const sessionResourceId = this.#session.identity.getResourceId();
-		if (!identity.resolved) {
-			this.#invalidateIdnode();
-			throw new KnowledgeInspectorError("unavailable", identity.reason ? `Knowledge inspection unavailable: ${identity.reason}` : "Knowledge inspection requires a resolved organization for this session.");
+		if (!session.resolved) {
+			this.#invalidate();
+			throw new KnowledgeInspectorError("unavailable", `Knowledge inspection unavailable: ${session.reason}`);
 		}
 		if (!sessionResourceId) throw new KnowledgeInspectorError("unavailable", "Knowledge inspection requires an active project.");
-		const organizationId = identity.organizationId;
-		const resourceId = identity.knowledgeResourceId ?? sessionResourceId;
+		const sessionTags = knowledgeSessionTags(session.scopes);
+		const resourceId = sessionResourceId;
 		const activeThreadId = this.#session.thread.getId() ?? void 0;
 		const thread = activeThreadId ? await this.#session.thread.getById({ threadId: activeThreadId }) : null;
 		const threadId = thread?.resourceId === sessionResourceId ? thread.id : void 0;
-		const fingerprint = `${organizationId}\0${resourceId}\0${threadId ?? ""}`;
+		const fingerprint = `${sessionTags.join("")}\0${resourceId}\0${threadId ?? ""}`;
 		if (this.#fingerprint !== fingerprint) {
 			this.#fingerprint = fingerprint;
 			this.#identityKey = opaqueToken();
@@ -288,154 +280,179 @@ var ScopedKnowledgeInspector = class {
 			this.#cursors.clear();
 		}
 		return {
-			organizationId,
+			sessionTags,
 			resourceId,
 			threadId,
 			fingerprint,
 			identityKey: this.#identityKey
 		};
 	}
-	#scope(binding, level) {
-		if (level === "org") return [`org:${binding.organizationId}`];
-		const scope = [`org:${binding.organizationId}`, `resource:${binding.resourceId}`];
-		if (level === "resource") return scope;
-		if (!binding.threadId) throw new KnowledgeInspectorError("unavailable", "The active thread does not belong to this project.");
-		return [...scope, `thread:${binding.threadId}`];
+	/** The principals a level reads with: the session's shared tags, plus its resource, plus its thread. */
+	async #view(binding, level) {
+		let principals;
+		if (level === "org") {
+			if (binding.sessionTags.length === 0) throw new KnowledgeInspectorError("unavailable", "This session holds no shared scope tags.");
+			principals = [...binding.sessionTags];
+		} else {
+			principals = [...binding.sessionTags, `resource:${binding.resourceId}`];
+			if (level === "thread") {
+				if (!binding.threadId) throw new KnowledgeInspectorError("unavailable", "The active thread does not belong to this project.");
+				principals.push(`thread:${binding.threadId}`);
+			}
+		}
+		try {
+			return {
+				level,
+				read: await this.#knowledge.readScopeFor(principals.map(canonical))
+			};
+		} catch (error) {
+			throw new KnowledgeInspectorError("unavailable", `Knowledge inspection unavailable: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 	async #assertStable(binding) {
 		const current = await this.#binding();
 		if (current.identityKey !== binding.identityKey || current.fingerprint !== binding.fingerprint) throw new KnowledgeInspectorError("stale-handle", "Knowledge scope changed while the request was running.");
 	}
-	#assertVisible(record, scope) {
-		if (!record || !isKnowledgeScopeVisible(record.scope, scope)) throw new KnowledgeInspectorError("not-visible", "Knowledge record is not visible in the selected scope.");
+	async #scopeAddress(scopeId) {
+		if (!this.#scopeAddresses.has(scopeId)) {
+			const page = await this.#store.getPage({
+				id: scopeId,
+				read: "all"
+			});
+			this.#scopeAddresses.set(scopeId, page?.address);
+		}
+		return this.#scopeAddresses.get(scopeId);
+	}
+	async #summary(page, binding, view) {
+		return {
+			handle: this.#mintHandle(binding, view.level, "node", page.id),
+			id: page.id,
+			type: "node",
+			name: page.name,
+			scope: badgeOf(await this.#scopeAddress(page.scopeId)),
+			version: page.version,
+			updatedAt: page.updatedAt.toISOString()
+		};
 	}
-	#recordSummary(record, binding, level) {
-		const type = "node";
+	async #noteSummary(note) {
 		return {
-			handle: this.#mintHandle(binding, level, type, record.id),
-			type,
-			name: record.name,
-			kind: record.kind,
-			scope: scopeBadge(record.scope),
-			version: record.version,
-			updatedAt: record.updatedAt.toISOString()
+			text: note.text,
+			scope: badgeOf(await this.#scopeAddress(note.stampScopeIds[0])),
+			sourceThreadId: note.provenance.sourceThreadId,
+			capturedAt: note.createdAt.toISOString(),
+			when: note.when?.toISOString()
 		};
 	}
-	async #rankedNodeSnapshot(scope, namePrefix, kind, sort) {
-		const records = await this.#knowledge.listNodes({
-			scope,
+	/** The first pages by name, most linked first; ties keep name order. */
+	async #ranked(view, namePrefix) {
+		const { pages } = await this.#store.listPages({
+			read: view.read,
 			namePrefix,
-			kind,
 			limit: MAX_RANK_CANDIDATES
 		});
-		const ranked = await Promise.all(records.map(async (node, recencyRank) => ({
-			node,
-			recencyRank,
-			...await this.#sampledRelationshipCounts(node, scope)
-		})));
-		const connected = [...ranked].sort((a, b) => b.degree - a.degree || a.recencyRank - b.recencyRank || a.node.id.localeCompare(b.node.id));
-		const connectedRank = new Map(connected.map((entry, index) => [entry.node.id, index]));
+		const ranked = await Promise.all(pages.map(async (page, order) => {
+			const counts = await this.#counts(page, view);
+			return {
+				id: page.id,
+				order,
+				counts,
+				degree: counts.outgoing + counts.incoming
+			};
+		}));
+		ranked.sort((a, b) => b.degree - a.degree || a.order - b.order);
 		return {
 			offset: 0,
-			entries: (sort === "connected" ? connected : [...ranked].sort((a, b) => {
-				const aScore = 1 / (RRF_K + a.recencyRank + 1) + 1 / (RRF_K + connectedRank.get(a.node.id) + 1);
-				return 1 / (RRF_K + b.recencyRank + 1) + 1 / (RRF_K + connectedRank.get(b.node.id) + 1) - aScore || a.recencyRank - b.recencyRank || a.node.id.localeCompare(b.node.id);
-			})).map((entry) => ({
-				id: entry.node.id,
-				degree: entry.degree,
-				counts: entry.counts
+			entries: ranked.map(({ id, counts }) => ({
+				id,
+				counts
 			}))
 		};
 	}
-	async #sampledRelationshipCounts(node, scope) {
-		const [aboutResult, mentioningResult] = await Promise.all([this.#knowledge.listKnowledgeAbout({
-			node: node.id,
-			scope,
-			limit: MAX_RANK_FACTS
-		}), this.#knowledge.listKnowledgeMentioning({
-			node: node.id,
-			scope,
-			limit: MAX_RANK_FACTS
+	async #counts(page, view) {
+		const [notes, mentioning] = await Promise.all([this.#store.listNotes({
+			pageId: page.id,
+			read: view.read,
+			limit: MAX_RANK_NOTES
+		}), this.#store.listNotesMentioning({
+			pageId: page.id,
+			read: view.read,
+			limit: MAX_RANK_NOTES
 		})]);
-		const [outgoing, incoming] = await Promise.all([this.#outgoingNodeRecords(node, aboutResult.records, scope), this.#incomingParentRecords(node, mentioningResult.records, scope)]);
-		const mentioningRecords = mentioningResult.records.filter((record) => record.node !== node.id);
+		const [outgoing, incoming] = await Promise.all([this.#outgoing(page, notes.notes, view), this.#incoming(mentioning.notes, view)]);
 		return {
-			degree: new Set([...outgoing.nodes, ...incoming.nodes].map((record) => record.id)).size,
-			counts: {
-				records: aboutResult.records.length + mentioningRecords.length,
-				outgoing: outgoing.nodes.length,
-				incoming: incoming.nodes.length,
-				sampled: Boolean(aboutResult.nextCursor || mentioningResult.nextCursor || outgoing.truncated || incoming.truncated)
-			}
+			records: notes.notes.length + mentioning.notes.length,
+			outgoing: outgoing.pages.length,
+			incoming: incoming.pages.length,
+			sampled: Boolean(notes.nextCursor || mentioning.nextCursor || outgoing.truncated || incoming.truncated)
 		};
 	}
-	async #outgoingNodeRecords(current, records, scope) {
+	/** Readable pages this page's notes mention, then pages its body links to by name. */
+	async #outgoing(page, notes, view) {
 		const related = /* @__PURE__ */ new Map();
-		let truncated = false;
-		const sources = [current.content ?? "", ...records.map((record) => record.text)];
-		for (const source of sources) {
-			for (const name of parseKnowledgeWikilinks(source)) {
-				if (related.size >= MAX_RELATED_RECORDS) {
-					truncated = true;
-					break;
-				}
-				const node = await this.#knowledge.resolveNode({
-					name,
-					scope
-				});
-				if (node && node.id !== current.id && isKnowledgeScopeVisible(node.scope, scope)) related.set(node.id, node);
-			}
-			if (truncated) break;
+		const add = (target) => {
+			if (target && !target.deletedAt && target.id !== page.id) related.set(target.id, target);
+		};
+		for (const id of new Set(notes.flatMap((note) => note.mentions))) {
+			if (related.size >= MAX_RELATED_PAGES) return {
+				pages: [...related.values()],
+				truncated: true
+			};
+			add(await this.#store.getPage({
+				id,
+				read: view.read
+			}));
+		}
+		for (const name of parseKnowledgeWikilinks(page.body ?? "")) {
+			if (related.size >= MAX_RELATED_PAGES) return {
+				pages: [...related.values()],
+				truncated: true
+			};
+			const [target] = await this.#store.findPagesByName({
+				name,
+				read: view.read,
+				limit: 1
+			});
+			add(target);
 		}
 		return {
-			nodes: [...related.values()],
-			truncated
+			pages: [...related.values()],
+			truncated: false
 		};
 	}
-	async #incomingParentRecords(current, records, scope) {
+	/** Readable pages whose notes mention this page. */
+	async #incoming(mentioning, view) {
 		const related = /* @__PURE__ */ new Map();
-		let truncated = false;
-		for (const record of records) {
-			if (record.node === current.id || related.has(record.node)) continue;
-			if (related.size >= MAX_RELATED_RECORDS) {
-				truncated = true;
-				break;
-			}
-			const node = await this.#knowledge.getNode(record.node);
-			if (node && isKnowledgeScopeVisible(node.scope, scope)) related.set(node.id, node);
+		for (const pageId of new Set(mentioning.map((note) => note.pageId))) {
+			if (related.size >= MAX_RELATED_PAGES) return {
+				pages: [...related.values()],
+				truncated: true
+			};
+			const source = await this.#store.getPage({
+				id: pageId,
+				read: view.read
+			});
+			if (source && !source.deletedAt) related.set(source.id, source);
 		}
 		return {
-			nodes: [...related.values()],
-			truncated
+			pages: [...related.values()],
+			truncated: false
 		};
 	}
-	async #outgoingTargets(current, records, scope, binding, level) {
-		const related = await this.#outgoingNodeRecords(current, records, scope);
-		return {
-			nodes: related.nodes.map((node) => this.#recordSummary(node, binding, level)),
-			partial: related.truncated
-		};
-	}
-	async #incomingParents(current, records, scope, binding, level) {
-		const related = await this.#incomingParentRecords(current, records, scope);
+	async #activityEvent(event, binding, view) {
+		const page = await this.#store.getPage({
+			id: event.pageId,
+			read: view.read
+		});
+		const live = page && !page.deletedAt ? page : void 0;
 		return {
-			nodes: related.nodes.map((node) => this.#recordSummary(node, binding, level)),
-			partial: related.truncated
+			action: event.action,
+			recordType: event.noteId ? "note" : "page",
+			scope: badgeOf(await this.#scopeAddress(event.scopeId)),
+			sourceThreadId: event.provenance.sourceThreadId,
+			createdAt: event.createdAt.toISOString(),
+			record: live ? await this.#summary(live, binding, view) : void 0
 		};
 	}
-	async #activityRecord(event, scope, binding, level) {
-		if (event.recordType === "node") {
-			const node = await this.#knowledge.getNode(event.recordId);
-			return node && isKnowledgeScopeVisible(node.scope, scope) ? this.#recordSummary(node, binding, level) : void 0;
-		}
-		const record = await this.#knowledge.getKnowledge({
-			id: event.recordId,
-			includeDeleted: true
-		});
-		if (!record || !isKnowledgeScopeVisible(record.scope, scope)) return void 0;
-		const node = await this.#knowledge.getNode(record.node);
-		return node && isKnowledgeScopeVisible(node.scope, scope) ? this.#recordSummary(node, binding, level) : void 0;
-	}
 	#mintHandle(binding, level, type, recordId) {
 		this.#pruneOpaqueEntries();
 		const token = opaqueToken();
@@ -470,7 +487,7 @@ var ScopedKnowledgeInspector = class {
 	#consumeCursor(cursor, binding, level, kind, filters) {
 		if (!cursor) return void 0;
 		const entry = this.#cursors.get(cursor);
-		if (!entry || entry.expiresAt < Date.now() || entry.identityKey !== binding.identityKey || entry.level !== level || entry.kind !== kind || entry.filters?.namePrefix !== filters?.namePrefix || entry.filters?.kind !== filters?.kind || entry.filters?.sort !== filters?.sort) throw new KnowledgeInspectorError("invalid-cursor", "Knowledge cursor does not match the active scope and filters.");
+		if (!entry || entry.expiresAt < Date.now() || entry.identityKey !== binding.identityKey || entry.level !== level || entry.kind !== kind || entry.filters?.namePrefix !== filters?.namePrefix || entry.filters?.sort !== filters?.sort) throw new KnowledgeInspectorError("invalid-cursor", "Knowledge cursor does not match the active scope and filters.");
 		return entry.value;
 	}
 	#pruneOpaqueEntries() {
@@ -487,13 +504,18 @@ var ScopedKnowledgeInspector = class {
 			}
 		}
 	}
-	#invalidateIdnode() {
+	#invalidate() {
 		this.#fingerprint = void 0;
 		this.#identityKey = opaqueToken();
 		this.#handles.clear();
 		this.#cursors.clear();
 	}
 };
+/**
+* The /knowledge inspector for a session, reading through the session's Knowledge runtime (a key
+* resolves through `mastra`). Undefined when there is no Knowledge runtime: access rules live on the
+* runtime, so a bare storage domain can't be inspected.
+*/
 async function createKnowledgeInspector(input) {
 	let selected;
 	if (typeof input.knowledge === "string") {
@@ -504,11 +526,14 @@ async function createKnowledgeInspector(input) {
 		}
 		if (!selected) throw new KnowledgeInspectorError("unavailable", "The configured Knowledge runtime is unavailable.");
 	} else selected = input.knowledge;
-	const knowledge = selected ? await selected.getStorage() : await input.storage.getStore("knowledge");
-	return knowledge ? new ScopedKnowledgeInspector({
-		knowledge,
-		session: input.session
-	}) : void 0;
+	if (!selected) return void 0;
+	const store = await selected.getStorage();
+	return new ScopedKnowledgeInspector({
+		knowledge: selected,
+		store,
+		session: input.session,
+		hostScopes: input.hostScopes
+	});
 }
 export { KnowledgeInspectorError, createKnowledgeInspector };