@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/routes/knowledge.js

@@ -0,0 +1,1128 @@
+import { Route } from "./route.js";
+import { registerApiRoute } from "@mastra/core/server";
+import { KnowledgeUnsupportedCapabilityError, canonicalizeKnowledgeScope, isKnowledgeScopeVisible, knowledgeScopeKey, parseKnowledgeWikilinks } from "@mastra/core/storage";
+//#region src/routes/knowledge.ts
+/** Reserved node that anchors pinned records (see subconscious/pinned.ts). */
+const PINNED_NODE_NAME = "pinned";
+/** Hover-card budget for record text shipped in the graph payload. */
+const RECORD_TEXT_LIMIT = 240;
+function truncateRecordText(text) {
+	return text.length > RECORD_TEXT_LIMIT ? `${text.slice(0, RECORD_TEXT_LIMIT - 1)}…` : text;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Authorized visible events returned per activity page. */
+const ACTIVITY_PAGE_SIZE = 25;
+/** Events fetched per `listActivity` batch while filling a visible page. */
+const ACTIVITY_BATCH = 100;
+/** Hard scan cap so a huge hidden backlog cannot spin the request. */
+const ACTIVITY_SCAN_CAP = 1e3;
+/** Maximum visible nodes inspected for non-prefix name matches. */
+const SEARCH_SCAN_CAP = 1e3;
+/** Compact result window returned to the search popover. */
+const SEARCH_RESULT_LIMIT = 20;
+/** Prevent an unbounded query string from reaching storage. */
+const SEARCH_QUERY_LIMIT = 128;
+/** Scope nodes returned per parent while lazily expanding the tree. */
+const SCOPE_PAGE_SIZE = 25;
+/** Bound storage pressure while calculating direct-member counts. */
+const SCOPE_COUNT_CONCURRENCY = 8;
+const DEFAULT_LIMITS = {
+	maxNodes: 500,
+	maxRecords: 2e3,
+	maxFallbackLookups: 100,
+	maxOrgScopePages: 10
+};
+function loose(c) {
+	return c;
+}
+function deepestRung(scope) {
+	let rung = "org";
+	for (const entry of scope) {
+		const ns = entry.slice(0, entry.indexOf(":"));
+		if (ns === "thread") return "thread";
+		if (ns === "resource") rung = "resource";
+	}
+	return rung;
+}
+/**
+* True when `scope` is a prefix of the active view scope — the content lives
+* inside the current org + project boundary. Structural member lenses use
+* this to keep sibling-project knowledge out of a project-scoped view.
+*/
+function withinViewBoundary(scope, viewScope) {
+	return scope.length <= viewScope.length && scope.every((entry, index) => entry === viewScope[index]);
+}
+function directScopeMemberCounts({ members, hasMore }, childScopeCount, viewScope, maxNodes) {
+	const contentNodeCount = members.filter((member) => !member.isScope && Array.isArray(member.scope) && withinViewBoundary(member.scope, viewScope)).length;
+	const directMemberCount = childScopeCount + contentNodeCount;
+	return {
+		memberCount: Math.min(directMemberCount, maxNodes),
+		memberCountTruncated: directMemberCount > maxNodes || hasMore,
+		contentNodeCount,
+		childScopeCount
+	};
+}
+function compareScopeNodes(a, b) {
+	return a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
+}
+/**
+* Scopes in one org (the org scope and everything beneath it), filtered and paged in storage.
+* Reads at most `maxPages` pages; `truncated` is true when scopes remain past that point.
+*/
+async function listOrgScopeNodes(store, orgId, maxPages) {
+	const scopes = [];
+	let cursor;
+	for (let page = 0; page < maxPages; page += 1) {
+		const result = await store.listScopeNodes({
+			withinAddress: `org:${orgId}`,
+			cursor
+		});
+		scopes.push(...result.scopes);
+		if (!result.nextCursor) return {
+			scopes,
+			truncated: false
+		};
+		cursor = result.nextCursor;
+	}
+	return {
+		scopes,
+		truncated: true
+	};
+}
+/** One scope node, only if it is in the org. Independent of how many scopes the org has. */
+async function findOrgScopeNode(store, orgId, scopeNodeId) {
+	const { scopes } = await store.listScopeNodes({
+		withinAddress: `org:${orgId}`,
+		ids: [scopeNodeId],
+		limit: 1
+	});
+	return scopes[0];
+}
+function knowledgeSearchRank(name, query) {
+	const normalized = name.toLocaleLowerCase();
+	if (normalized === query) return 0;
+	if (normalized.startsWith(query)) return 1;
+	return 2;
+}
+/**
+* What a scope node is, for labels: the rung name for vouched identity scopes, otherwise the
+* stored kind, or "topic" for structural scopes created without one. Matches the scope list.
+*/
+function scopeKindLabel(address, kind) {
+	if (address.startsWith("org:")) return "org";
+	if (address.startsWith("resource:")) return "project";
+	if (address.startsWith("thread:")) return "session";
+	return kind || "topic";
+}
+/** The thread id of a session (`thread:<id>`) scope node, or undefined for any other scope. */
+function sessionThreadId(node) {
+	return node.address.startsWith("thread:") ? boundedThreadId(node.address.slice(7)) : void 0;
+}
+function boundedThreadId(raw) {
+	if (!raw) return void 0;
+	const trimmed = raw.trim();
+	return trimmed.length > 0 && trimmed.length <= 512 ? trimmed : void 0;
+}
+/**
+* In-record + capped-fallback wikilink resolver, shared by both endpoints.
+* Resolution uses the store's own algorithm: a descending-prefix walk over the
+* record's canonical scope matching canonical name + exact scope key at each
+* prefix, so an edge never depends on whether the target landed in the window.
+*/
+var WikilinkResolver = class {
+	/** exact `${scopeKey}\u0000${lowerName}` → node, from the fetched window. */
+	#inWindow = /* @__PURE__ */ new Map();
+	#windowIds = /* @__PURE__ */ new Set();
+	/** `${recordScopeKey}\u0000${lowerName}` → fallback result (null = dangling). */
+	#fallbackCache = /* @__PURE__ */ new Map();
+	#fallbackLookups = 0;
+	#store;
+	#maxFallbackLookups;
+	outOfWindow = /* @__PURE__ */ new Map();
+	cappedNames = [];
+	#cappedSeen = /* @__PURE__ */ new Set();
+	constructor(store, nodes, maxFallbackLookups) {
+		this.#store = store;
+		this.#maxFallbackLookups = maxFallbackLookups;
+		for (const node of nodes) {
+			this.#inWindow.set(`${knowledgeScopeKey(node.scope)}\u0000${node.name.trim().toLocaleLowerCase()}`, node);
+			this.#windowIds.add(node.id);
+		}
+	}
+	inWindowId(id) {
+		return this.#windowIds.has(id);
+	}
+	/** Resolve a wikilink name from a knowledge record's scope. Returns the node or null (dangling/capped). */
+	async resolve(name, recordScope) {
+		const canonical = canonicalizeKnowledgeScope(recordScope);
+		const lower = name.trim().toLocaleLowerCase();
+		for (let length = canonical.length; length > 0; length--) {
+			const hit = this.#inWindow.get(`${knowledgeScopeKey(canonical.slice(0, length))}\u0000${lower}`);
+			if (hit) return hit;
+		}
+		const cacheKey = `${knowledgeScopeKey(canonical)}\u0000${lower}`;
+		if (this.#fallbackCache.has(cacheKey)) return this.#trackOutOfWindow(this.#fallbackCache.get(cacheKey) ?? null);
+		if (this.#fallbackLookups >= this.#maxFallbackLookups) {
+			if (!this.#cappedSeen.has(lower) && this.cappedNames.length < 100) {
+				this.#cappedSeen.add(lower);
+				this.cappedNames.push(name.trim());
+			} else if (!this.#cappedSeen.has(lower)) this.#cappedSeen.add(lower);
+			return null;
+		}
+		this.#fallbackLookups += 1;
+		let resolved = null;
+		try {
+			resolved = await this.#store.resolveNode({
+				name,
+				scope: canonical
+			});
+		} catch {
+			resolved = null;
+		}
+		this.#fallbackCache.set(cacheKey, resolved);
+		return this.#trackOutOfWindow(resolved);
+	}
+	#trackOutOfWindow(node) {
+		if (node && !this.#windowIds.has(node.id)) this.outOfWindow.set(node.id, {
+			id: node.id,
+			name: node.name,
+			scope: node.scope,
+			rung: deepestRung(node.scope)
+		});
+		return node;
+	}
+	get cappedCount() {
+		return this.#cappedSeen.size;
+	}
+};
+var KnowledgeRoutes = class extends Route {
+	#limits;
+	constructor(deps) {
+		super(deps);
+		this.#limits = {
+			...DEFAULT_LIMITS,
+			...deps.limits
+		};
+	}
+	/** Resolve the `(orgId, userId)` tenant or a ready-to-return error response. */
+	async #resolveTenant(c) {
+		await this.deps.auth.ensureUser(c);
+		const tenant = this.deps.auth.tenant(c);
+		if (!tenant) return { response: c.json({ error: "unauthorized" }, 401) };
+		if (!tenant.orgId) return { response: c.json({
+			error: "organization_required",
+			message: "The knowledge graph requires an organization."
+		}, 403) };
+		return {
+			orgId: tenant.orgId,
+			userId: tenant.userId
+		};
+	}
+	/**
+	* Resolve tenant + org-owned project + knowledge store + the active view's
+	* query scope. The ONE seam both endpoints share, so the default/thread view
+	* scope and the pin rungs cannot drift between them.
+	*
+	* threadId validation runs a single `listRecordsBySource` lookup with
+	* `limit: 1` AT THE CANDIDATE SCOPE `[org, resource, thread:<id>]` — the
+	* store's own visibility predicate is the authorization: the thread's own
+	* records (equal scope key) and its project/org captures (prefix) match, while
+	* a cross-org thread's records match nothing → zero rows → 404.
+	*/
+	async #resolveView(c) {
+		const tenant = await this.#resolveTenant(c);
+		if ("response" in tenant) return tenant;
+		const projectId = c.req.param("id");
+		if (!projectId || !UUID_RE.test(projectId)) return { response: c.json({ error: "Project not found" }, 404) };
+		const { projects } = this.deps;
+		await projects.ensureReady();
+		const project = await projects.get({
+			orgId: tenant.orgId,
+			id: projectId
+		});
+		if (!project) return { response: c.json({ error: "Project not found" }, 404) };
+		let knowledge;
+		let store;
+		try {
+			const key = this.deps.defaultKnowledgeKey ?? "default";
+			knowledge = await this.deps.knowledge(key);
+			store = knowledge ? await knowledge.getStorage() : void 0;
+		} catch {
+			store = void 0;
+		}
+		if (!store || !knowledge) return { response: c.json({
+			error: "knowledge_unavailable",
+			message: "The configured Knowledge runtime is unavailable."
+		}, 503) };
+		const defaultScope = [`org:${tenant.orgId}`, `resource:${projectId}`];
+		const resourceRungScope = defaultScope;
+		const threadId = boundedThreadId(c.req.query("threadId"));
+		if (c.req.query("threadId") !== void 0 && !threadId) return { response: c.json({ error: "thread_not_found" }, 404) };
+		if (!threadId) return {
+			...tenant,
+			factoryProjectId: projectId,
+			factoryProjectName: project.name,
+			knowledge,
+			store,
+			view: "project",
+			scope: defaultScope,
+			pinRungs: [{
+				rung: "resource",
+				scope: resourceRungScope
+			}]
+		};
+		const candidateScope = [...defaultScope, `thread:${threadId}`];
+		if ((await store.knowledgeBySource({
+			sourceThreadId: threadId,
+			scope: candidateScope,
+			limit: 1
+		})).records.length === 0) return { response: c.json({ error: "thread_not_found" }, 404) };
+		return {
+			...tenant,
+			factoryProjectId: projectId,
+			factoryProjectName: project.name,
+			knowledge,
+			store,
+			view: "thread",
+			threadId,
+			scope: candidateScope,
+			pinRungs: [{
+				rung: "resource",
+				scope: resourceRungScope
+			}, {
+				rung: "thread",
+				scope: candidateScope
+			}]
+		};
+	}
+	#selectedView(view, level) {
+		const projectView = {
+			orgId: view.orgId,
+			userId: view.userId,
+			factoryProjectId: view.factoryProjectId,
+			factoryProjectName: view.factoryProjectName,
+			knowledge: view.knowledge,
+			store: view.store,
+			view: "project"
+		};
+		if (level === "org") return {
+			...projectView,
+			scope: view.scope.slice(0, 1),
+			pinRungs: []
+		};
+		if (level === "resource") return {
+			...projectView,
+			scope: view.scope.slice(0, 2),
+			pinRungs: view.pinRungs.filter((rung) => rung.rung === "resource")
+		};
+		if (level === "thread" && view.threadId) return view;
+	}
+	/**
+	* Host-vouched identity chain: the org → project → session rungs this
+	* request resolved are materialized as ordinary scope nodes linked by
+	* membership edges, so the sidebar tree is built from scopes that EXIST —
+	* never from the declared structure plan or the rung config. Materialization
+	* is create-only and deduped by address (existing nodes keep their declared
+	* names/parents), so the steady state is a no-op skip. No companion scope is
+	* created here or anywhere automatically. A vouch failure never fails the read —
+	* the tree simply serves the scopes that already exist.
+	*/
+	async #vouchIdentityScopes(view) {
+		const orgAddress = `org:${view.orgId}`;
+		const resourceAddress = `resource:${view.factoryProjectId}`;
+		const chain = [
+			{
+				address: orgAddress,
+				contextualScopeAddress: orgAddress
+			},
+			{
+				address: resourceAddress,
+				name: view.factoryProjectName,
+				contextualScopeAddress: orgAddress,
+				parentAddresses: [orgAddress]
+			},
+			...view.threadId ? [{
+				address: `thread:${view.threadId}`,
+				contextualScopeAddress: resourceAddress,
+				parentAddresses: [resourceAddress]
+			}] : []
+		];
+		let existing;
+		try {
+			const { scopes } = await view.store.listScopeNodes({ addresses: chain.map((link) => link.address) });
+			existing = new Set(scopes.map((node) => node.address));
+		} catch (error) {
+			if (error instanceof KnowledgeUnsupportedCapabilityError) return;
+			throw error;
+		}
+		for (const link of chain) {
+			if (existing.has(link.address)) continue;
+			await view.knowledge.materializeScope(link).catch(() => void 0);
+		}
+	}
+	/**
+	* Session scopes are listed only under the viewed project, and only when the `threadId`
+	* drill-down would accept them (a visible record captured in that session), so no listing
+	* exposes a session id the drill-down would reject. Returns the ids of hidden session nodes.
+	* With `probe: false` only the cheap project check runs; callers probe the bounded page they return.
+	*/
+	async #hiddenSessionIds(view, nodes, projectNodeId, { probe }) {
+		const hidden = /* @__PURE__ */ new Set();
+		const projectScope = [`org:${view.orgId}`, `resource:${view.factoryProjectId}`];
+		const sessions = [];
+		for (const node of nodes) {
+			if (!node.address.startsWith("thread:")) continue;
+			const threadId = sessionThreadId(node);
+			if (!threadId || !projectNodeId || !node.parentIds.includes(projectNodeId)) hidden.add(node.id);
+			else if (probe && threadId !== view.threadId) sessions.push({
+				id: node.id,
+				threadId
+			});
+		}
+		for (let index = 0; index < sessions.length; index += SCOPE_COUNT_CONCURRENCY) await Promise.all(sessions.slice(index, index + SCOPE_COUNT_CONCURRENCY).map(async ({ id, threadId }) => {
+			const { records } = await view.store.knowledgeBySource({
+				sourceThreadId: threadId,
+				scope: [...projectScope, `thread:${threadId}`],
+				limit: 1
+			});
+			if (records.length === 0) hidden.add(id);
+		}));
+		return hidden;
+	}
+	/**
+	* Display names for session scopes, resolved at read time from the thread's current title
+	* (never stored on the scope node, where it would go stale). Keyed by scope node id.
+	*/
+	async #sessionNames(nodes) {
+		const names = /* @__PURE__ */ new Map();
+		const sessions = nodes.flatMap((node) => {
+			const threadId = node.address.startsWith("thread:") ? node.address.slice(7) : "";
+			return threadId ? [{
+				id: node.id,
+				threadId
+			}] : [];
+		});
+		for (let index = 0; index < sessions.length; index += SCOPE_COUNT_CONCURRENCY) await Promise.all(sessions.slice(index, index + SCOPE_COUNT_CONCURRENCY).map(async ({ id, threadId }) => {
+			let title;
+			try {
+				title = (await this.deps.threadTitle?.(threadId))?.trim();
+			} catch {}
+			names.set(id, title || `session ${threadId.slice(0, 8)}`);
+		}));
+		return names;
+	}
+	/** Reserved `pinned` node ids at the active view's rungs (one exact-scope lookup per rung). */
+	async #pinnedNodeIds(view) {
+		const out = [];
+		for (const { rung, scope } of view.pinRungs) {
+			const node = await view.store.getNodeByName({
+				name: PINNED_NODE_NAME,
+				scope
+			});
+			if (node && !node.mergedInto) out.push({
+				rung,
+				id: node.id
+			});
+		}
+		return out;
+	}
+	/** Non-deleted pinned records for the given pinned-node ids, visible in the view. */
+	async #pinnedRecords(view, pinnedNodeIds) {
+		const out = [];
+		for (const { rung, id } of pinnedNodeIds) {
+			const { records } = await view.store.listKnowledgeAbout({
+				node: id,
+				scope: view.scope,
+				limit: 200
+			});
+			for (const record of records) out.push({
+				rung,
+				record
+			});
+		}
+		return out;
+	}
+	routes() {
+		return [
+			registerApiRoute("/web/factory/projects/:id/knowledge/scopes", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const view = await this.#resolveView(loose(c));
+					if ("response" in view) return view.response;
+					await this.#vouchIdentityScopes(view);
+					let scopeNodes;
+					let nextCursor;
+					const childCursors = {};
+					let storedScopeNodes = [];
+					let scopesTruncated = false;
+					try {
+						({scopes: storedScopeNodes, truncated: scopesTruncated} = await listOrgScopeNodes(view.store, view.orgId, this.#limits.maxOrgScopePages));
+						const projectNodeId = storedScopeNodes.find((node) => node.address === `resource:${view.factoryProjectId}`)?.id;
+						const foreignSessions = await this.#hiddenSessionIds(view, storedScopeNodes, projectNodeId, { probe: false });
+						storedScopeNodes = storedScopeNodes.filter((node) => !foreignSessions.has(node.id));
+						const scopeNodeById = new Map(storedScopeNodes.map((node) => [node.id, node]));
+						const childScopeCountByParent = /* @__PURE__ */ new Map();
+						for (const node of storedScopeNodes) for (const parentId of node.parentIds) childScopeCountByParent.set(parentId, (childScopeCountByParent.get(parentId) ?? 0) + 1);
+						const parentId = loose(c).req.query("parentId");
+						const cursor = loose(c).req.query("cursor");
+						if (parentId && !UUID_RE.test(parentId)) return c.json({ error: "invalid_scope_parent" }, 400);
+						if (cursor && !UUID_RE.test(cursor)) return c.json({ error: "invalid_scope_cursor" }, 400);
+						if (parentId && !scopeNodeById.has(parentId)) return c.json({ error: "scope_not_found" }, 404);
+						const siblings = storedScopeNodes.filter((node) => parentId ? node.parentIds.includes(parentId) : node.parentIds.length === 0).sort(compareScopeNodes);
+						const cursorIndex = cursor ? siblings.findIndex((node) => node.id === cursor) : -1;
+						if (cursor && cursorIndex < 0) return c.json({ error: "invalid_scope_cursor" }, 400);
+						const pageStart = cursorIndex + 1;
+						const siblingPage = siblings.slice(pageStart, pageStart + SCOPE_PAGE_SIZE);
+						if (pageStart + siblingPage.length < siblings.length) nextCursor = siblingPage.at(-1)?.id;
+						const returnedById = new Map(siblingPage.map((node) => [node.id, node]));
+						if (!parentId) {
+							const addFirstChildPage = (parent) => {
+								const children = storedScopeNodes.filter((node) => node.parentIds.includes(parent.id)).sort(compareScopeNodes);
+								const returnedChildren = [];
+								for (const child of children.slice(0, SCOPE_PAGE_SIZE)) {
+									if (returnedById.size >= this.#limits.maxNodes) break;
+									returnedById.set(child.id, child);
+									returnedChildren.push(child);
+								}
+								if (returnedChildren.length < children.length) {
+									const lastChild = returnedChildren.at(-1);
+									if (lastChild) childCursors[parent.id] = lastChild.id;
+								}
+							};
+							for (const root of siblingPage) addFirstChildPage(root);
+							const identityAddresses = /* @__PURE__ */ new Set([
+								`org:${view.orgId}`,
+								`resource:${view.factoryProjectId}`,
+								...view.threadId ? [`thread:${view.threadId}`] : []
+							]);
+							const includeWithParents = (node) => {
+								if (returnedById.has(node.id) || returnedById.size >= this.#limits.maxNodes) return;
+								for (const ancestorId of node.parentIds) {
+									const ancestor = scopeNodeById.get(ancestorId);
+									if (ancestor) includeWithParents(ancestor);
+								}
+								returnedById.set(node.id, node);
+							};
+							for (const node of storedScopeNodes) if (identityAddresses.has(node.address)) includeWithParents(node);
+							const projectNode = projectNodeId ? scopeNodeById.get(projectNodeId) : void 0;
+							if (projectNode && returnedById.has(projectNode.id)) addFirstChildPage(projectNode);
+						}
+						const unreadableSessions = await this.#hiddenSessionIds(view, [...returnedById.values()], projectNodeId, { probe: true });
+						for (const id of unreadableSessions) returnedById.delete(id);
+						scopeNodes = [];
+						const returnedNodes = [...returnedById.values()].sort(compareScopeNodes);
+						for (let index = 0; index < returnedNodes.length; index += SCOPE_COUNT_CONCURRENCY) {
+							const batch = returnedNodes.slice(index, index + SCOPE_COUNT_CONCURRENCY);
+							scopeNodes.push(...await Promise.all(batch.map(async (node) => {
+								const members = await view.store.listScopeMembers({
+									scopeNodeId: node.id,
+									limit: this.#limits.maxNodes
+								});
+								return {
+									...node,
+									...node.address === `resource:${view.factoryProjectId}` ? { name: view.factoryProjectName } : {},
+									...directScopeMemberCounts(members, childScopeCountByParent.get(node.id) ?? 0, view.scope, this.#limits.maxNodes)
+								};
+							})));
+						}
+						const sessionNames = await this.#sessionNames(scopeNodes);
+						scopeNodes = scopeNodes.map((node) => ({
+							...node,
+							kind: scopeKindLabel(node.address, node.kind),
+							...sessionNames.has(node.id) ? { name: sessionNames.get(node.id) } : {}
+						}));
+					} catch (error) {
+						if (!(error instanceof KnowledgeUnsupportedCapabilityError)) throw error;
+						scopeNodes = void 0;
+					}
+					const scopeNodeByAddress = new Map(storedScopeNodes.map((node) => [node.address, node]));
+					const threadRoot = view.threadId ? scopeNodeByAddress.get(`thread:${view.threadId}`) : void 0;
+					const threadRootName = threadRoot ? (await this.#sessionNames([threadRoot])).get(threadRoot.id) : void 0;
+					const rungs = [
+						{
+							level: "org",
+							id: view.orgId,
+							available: true
+						},
+						{
+							level: "resource",
+							id: view.factoryProjectId,
+							available: true
+						},
+						...view.threadId ? [{
+							level: "thread",
+							id: view.threadId,
+							available: true
+						}] : []
+					];
+					return c.json({
+						roots: rungs.map((rung) => {
+							const match = scopeNodeByAddress.get(`${rung.level}:${rung.id}`);
+							const name = match?.address === `resource:${view.factoryProjectId}` ? view.factoryProjectName : match && rung.level === "thread" ? threadRootName : match?.name;
+							return match ? {
+								...rung,
+								scopeNodeId: match.id,
+								name
+							} : rung;
+						}),
+						defaultLevel: "resource",
+						...scopeNodes ? { scopeNodes } : {},
+						...nextCursor ? { nextCursor } : {},
+						...Object.keys(childCursors).length > 0 ? { childCursors } : {},
+						...scopesTruncated ? { truncated: true } : {}
+					});
+				}
+			}),
+			registerApiRoute("/web/factory/projects/:id/knowledge/search", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const view = await this.#resolveView(loose(c));
+					if ("response" in view) return view.response;
+					const query = (loose(c).req.query("q") ?? "").trim().slice(0, SEARCH_QUERY_LIMIT).toLocaleLowerCase();
+					if (query.length < 2) return c.json({
+						results: [],
+						truncated: false
+					});
+					const scanLimit = Math.min(SEARCH_SCAN_CAP, this.#limits.maxNodes);
+					const [prefixNodes, scannedNodes] = await Promise.all([view.store.listNodes({
+						scope: view.scope,
+						namePrefix: query,
+						limit: 21
+					}), view.store.listNodes({
+						scope: view.scope,
+						limit: scanLimit
+					})]);
+					const contentById = /* @__PURE__ */ new Map();
+					for (const node of [...prefixNodes, ...scannedNodes]) {
+						if (node.isScope || !Array.isArray(node.scope) || !withinViewBoundary(node.scope, view.scope) || !node.name.toLocaleLowerCase().includes(query)) continue;
+						contentById.set(node.id, node);
+					}
+					let structuralScopes = [];
+					let scopesTruncated = false;
+					try {
+						const orgScopes = await listOrgScopeNodes(view.store, view.orgId, this.#limits.maxOrgScopePages);
+						scopesTruncated = orgScopes.truncated;
+						structuralScopes = orgScopes.scopes.filter((node) => (!node.address.startsWith("thread:") || sessionThreadId(node) === view.threadId) && node.name.toLocaleLowerCase().includes(query));
+					} catch (error) {
+						if (!(error instanceof KnowledgeUnsupportedCapabilityError)) throw error;
+					}
+					const scopeSessionNames = await this.#sessionNames(structuralScopes);
+					const results = [...structuralScopes.map((scopeNode) => {
+						const rung = scopeNode.address === `org:${view.orgId}` ? "org" : scopeNode.address === `resource:${view.factoryProjectId}` ? "resource" : view.threadId && scopeNode.address === `thread:${view.threadId}` ? "thread" : null;
+						return {
+							id: scopeNode.id,
+							name: scopeNode.address === `resource:${view.factoryProjectId}` ? view.factoryProjectName : scopeSessionNames.get(scopeNode.id) ?? scopeNode.name,
+							kind: scopeKindLabel(scopeNode.address, scopeNode.kind),
+							type: "scope",
+							rung,
+							address: scopeNode.address,
+							...scopeNode.description ? { description: scopeNode.description } : {}
+						};
+					}), ...[...contentById.values()].map((node) => {
+						const rung = deepestRung(node.scope);
+						const threadId = rung === "thread" ? node.scope.find((address) => address.startsWith("thread:"))?.slice(7) : void 0;
+						return {
+							id: node.id,
+							name: node.name,
+							kind: node.kind,
+							type: "node",
+							rung,
+							...threadId ? { threadId } : {}
+						};
+					})].sort((a, b) => knowledgeSearchRank(a.name, query) - knowledgeSearchRank(b.name, query) || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+					return c.json({
+						results: results.slice(0, SEARCH_RESULT_LIMIT),
+						truncated: scopesTruncated || results.length > SEARCH_RESULT_LIMIT || prefixNodes.length > SEARCH_RESULT_LIMIT || scannedNodes.length >= scanLimit
+					});
+				}
+			}),
+			registerApiRoute("/web/factory/projects/:id/knowledge/subgraph", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const resolved = await this.#resolveView(loose(c));
+					if ("response" in resolved) return resolved.response;
+					const scopeNodeId = loose(c).req.query("scopeNodeId");
+					if (scopeNodeId !== void 0) {
+						if (!UUID_RE.test(scopeNodeId)) return c.json({ error: "scope_not_found" }, 404);
+						const limits = this.#limits;
+						const { store } = resolved;
+						let storedRoot;
+						try {
+							storedRoot = await findOrgScopeNode(store, resolved.orgId, scopeNodeId);
+						} catch (error) {
+							if (error instanceof KnowledgeUnsupportedCapabilityError) return c.json({ error: "scope_not_found" }, 404);
+							throw error;
+						}
+						if (!storedRoot) return c.json({ error: "scope_not_found" }, 404);
+						const { scopes: scopeNodes, truncated: scopesTruncated } = await listOrgScopeNodes(store, resolved.orgId, limits.maxOrgScopePages);
+						const rootSessionName = (await this.#sessionNames([storedRoot])).get(storedRoot.id);
+						const root = storedRoot.address === `resource:${resolved.factoryProjectId}` ? {
+							...storedRoot,
+							name: resolved.factoryProjectName
+						} : rootSessionName ? {
+							...storedRoot,
+							name: rootSessionName
+						} : storedRoot;
+						if (storedRoot.address.startsWith("thread:")) {
+							const projectNodeId = scopeNodes.find((node) => node.address === `resource:${resolved.factoryProjectId}`)?.id;
+							if ((await this.#hiddenSessionIds(resolved, [storedRoot], projectNodeId, { probe: true })).has(storedRoot.id)) return c.json({ error: "scope_not_found" }, 404);
+						}
+						const otherSessionIds = new Set(scopeNodes.filter((node) => node.address.startsWith("thread:") && sessionThreadId(node) !== resolved.threadId).map((node) => node.id));
+						const fetched = await store.listScopeMembers({
+							scopeNodeId,
+							limit: limits.maxNodes
+						});
+						const bounded = fetched.members.filter((node) => node.isScope && !otherSessionIds.has(node.id) || !node.isScope && Array.isArray(node.scope) && withinViewBoundary(node.scope, resolved.scope));
+						let truncated = scopesTruncated || fetched.hasMore || bounded.length > limits.maxNodes;
+						const members = bounded.slice(0, limits.maxNodes);
+						const contentMembers = members.filter((node) => !node.isScope && Array.isArray(node.scope));
+						const childScopeCountByParent = /* @__PURE__ */ new Map();
+						for (const node of scopeNodes) for (const parentId of node.parentIds) childScopeCountByParent.set(parentId, (childScopeCountByParent.get(parentId) ?? 0) + 1);
+						const scopeCountsById = /* @__PURE__ */ new Map([[root.id, directScopeMemberCounts(fetched, childScopeCountByParent.get(root.id) ?? 0, resolved.scope, limits.maxNodes)]]);
+						const memberScopes = members.filter((node) => node.isScope);
+						for (let index = 0; index < memberScopes.length; index += SCOPE_COUNT_CONCURRENCY) {
+							const batch = memberScopes.slice(index, index + SCOPE_COUNT_CONCURRENCY);
+							await Promise.all(batch.map(async (node) => {
+								const directMembers = await store.listScopeMembers({
+									scopeNodeId: node.id,
+									limit: limits.maxNodes
+								});
+								scopeCountsById.set(node.id, directScopeMemberCounts(directMembers, childScopeCountByParent.get(node.id) ?? 0, resolved.scope, limits.maxNodes));
+							}));
+						}
+						const recordWindow = [];
+						for (const node of contentMembers) {
+							if (recordWindow.length > limits.maxRecords) break;
+							const { records } = await store.listKnowledgeAbout({
+								node: node.id,
+								scope: node.scope,
+								limit: limits.maxRecords + 1 - recordWindow.length
+							});
+							recordWindow.push(...records);
+						}
+						recordWindow.sort((a, b) => b.id.localeCompare(a.id));
+						if (recordWindow.length > limits.maxRecords) {
+							truncated = true;
+							recordWindow.length = limits.maxRecords;
+						}
+						const resolver = new WikilinkResolver(store, contentMembers, limits.maxFallbackLookups);
+						const edges = [];
+						const graphRecords = [];
+						const edgeSeen = /* @__PURE__ */ new Set();
+						const recordCounts = /* @__PURE__ */ new Map();
+						for (const record of recordWindow) {
+							recordCounts.set(record.node, (recordCounts.get(record.node) ?? 0) + 1);
+							const nodeIds = [record.node];
+							for (const name of parseKnowledgeWikilinks(record.text)) {
+								const target = await resolver.resolve(name, record.scope);
+								if (!target) continue;
+								if (target.id === record.node) continue;
+								if (!resolver.inWindowId(target.id)) continue;
+								if (!nodeIds.includes(target.id)) nodeIds.push(target.id);
+								const key = `${record.node}\u0000${target.id}`;
+								if (edgeSeen.has(key)) continue;
+								edgeSeen.add(key);
+								edges.push({
+									id: `wikilink:${record.node}:${target.id}`,
+									source: record.node,
+									target: target.id,
+									type: "wikilink",
+									recordId: record.id
+								});
+							}
+							graphRecords.push({
+								id: record.id,
+								nodeIds,
+								pinned: false,
+								text: truncateRecordText(record.text)
+							});
+						}
+						for (const member of members) edges.push({
+							id: `contains:${root.id}:${member.id}`,
+							source: root.id,
+							target: member.id,
+							type: "contains"
+						});
+						const scopeAddressById = new Map(scopeNodes.map((node) => [node.id, node.address]));
+						const memberSessionNames = await this.#sessionNames(members.flatMap((node) => {
+							const address = node.isScope ? scopeAddressById.get(node.id) : void 0;
+							return address ? [{
+								id: node.id,
+								address
+							}] : [];
+						}));
+						const rootRow = await store.getNode(root.id);
+						const activity = await store.listActivity({
+							scope: resolved.scope,
+							limit: 1
+						});
+						const payload = {
+							view: resolved.view,
+							...resolved.threadId ? { threadId: resolved.threadId } : {},
+							nodes: [{
+								id: root.id,
+								name: root.name,
+								kind: scopeKindLabel(root.address, root.kind),
+								...root.description ? { description: root.description } : {},
+								scope: null,
+								rung: null,
+								isScope: true,
+								pinned: false,
+								recordCount: 0,
+								...scopeCountsById.get(root.id),
+								...rootRow ? {
+									createdAt: rootRow.createdAt.toISOString(),
+									updatedAt: rootRow.updatedAt.toISOString()
+								} : {}
+							}, ...members.map((node) => {
+								const nodeScope = Array.isArray(node.scope) ? node.scope : null;
+								const address = node.isScope ? scopeAddressById.get(node.id) : void 0;
+								return {
+									id: node.id,
+									name: memberSessionNames.get(node.id) ?? node.name,
+									kind: node.isScope ? scopeKindLabel(address ?? "", node.kind) : node.kind,
+									...node.description ? { description: node.description } : {},
+									scope: nodeScope,
+									rung: nodeScope ? deepestRung(nodeScope) : null,
+									...node.isScope ? {
+										isScope: true,
+										...scopeCountsById.get(node.id)
+									} : {},
+									pinned: false,
+									recordCount: recordCounts.get(node.id) ?? 0,
+									createdAt: node.createdAt.toISOString(),
+									updatedAt: node.updatedAt.toISOString()
+								};
+							})],
+							edges,
+							records: graphRecords,
+							truncated,
+							outOfWindow: [...resolver.outOfWindow.values()],
+							unresolvedCapped: {
+								count: resolver.cappedCount,
+								names: resolver.cappedNames
+							},
+							pinCensus: {
+								resource: 0,
+								thread: null
+							},
+							version: activity[0]?.id ?? null
+						};
+						return c.json(payload);
+					}
+					const view = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
+					if (!view) return c.json({ error: "scope_not_found" }, 404);
+					const { store, scope } = view;
+					const limits = this.#limits;
+					const fetched = (await store.listNodes({
+						scope,
+						limit: limits.maxNodes + 1
+					})).filter((node) => Array.isArray(node.scope));
+					let truncated = fetched.length > limits.maxNodes;
+					const pinnedNodeIds = await this.#pinnedNodeIds(view);
+					const pinnedNodeIdSet = new Set(pinnedNodeIds.map((p) => p.id));
+					const nodes = fetched.slice(0, limits.maxNodes).filter((node) => !pinnedNodeIdSet.has(node.id));
+					const recordWindow = [];
+					for (const node of nodes) {
+						if (recordWindow.length > limits.maxRecords) break;
+						const { records } = await store.listKnowledgeAbout({
+							node: node.id,
+							scope,
+							limit: limits.maxRecords + 1 - recordWindow.length
+						});
+						recordWindow.push(...records);
+					}
+					recordWindow.sort((a, b) => b.id.localeCompare(a.id));
+					if (recordWindow.length > limits.maxRecords) {
+						truncated = true;
+						recordWindow.length = limits.maxRecords;
+					}
+					const resolver = new WikilinkResolver(store, nodes, limits.maxFallbackLookups);
+					const edges = [];
+					const graphRecords = [];
+					const edgeSeen = /* @__PURE__ */ new Set();
+					const recordCounts = /* @__PURE__ */ new Map();
+					for (const record of recordWindow) {
+						recordCounts.set(record.node, (recordCounts.get(record.node) ?? 0) + 1);
+						const nodeIds = [record.node];
+						for (const name of parseKnowledgeWikilinks(record.text)) {
+							const target = await resolver.resolve(name, record.scope);
+							if (!target) continue;
+							if (target.id === record.node) continue;
+							if (!resolver.inWindowId(target.id)) continue;
+							if (!nodeIds.includes(target.id)) nodeIds.push(target.id);
+							const key = `${record.node}\u0000${target.id}`;
+							if (edgeSeen.has(key)) continue;
+							edgeSeen.add(key);
+							edges.push({
+								id: `wikilink:${record.node}:${target.id}`,
+								source: record.node,
+								target: target.id,
+								type: "wikilink",
+								recordId: record.id
+							});
+						}
+						graphRecords.push({
+							id: record.id,
+							nodeIds,
+							pinned: false,
+							text: truncateRecordText(record.text)
+						});
+					}
+					const pinnedRecords = await this.#pinnedRecords(view, pinnedNodeIds);
+					const accented = /* @__PURE__ */ new Set();
+					for (const { record } of pinnedRecords) {
+						const targets = [];
+						for (const name of parseKnowledgeWikilinks(record.text)) {
+							const target = await resolver.resolve(name, record.scope);
+							if (target && resolver.inWindowId(target.id) && !targets.includes(target.id)) targets.push(target.id);
+						}
+						graphRecords.push({
+							id: record.id,
+							nodeIds: targets,
+							pinned: true,
+							text: truncateRecordText(record.text)
+						});
+						if (targets.length === 1) {
+							accented.add(targets[0]);
+							continue;
+						}
+						for (let a = 0; a < targets.length; a += 1) for (let b = a + 1; b < targets.length; b += 1) {
+							const key = `${targets[a]}\u0000${targets[b]}\u0000pin`;
+							if (edgeSeen.has(key)) continue;
+							edgeSeen.add(key);
+							edges.push({
+								id: `pin:${record.id}:${targets[a]}:${targets[b]}`,
+								source: targets[a],
+								target: targets[b],
+								type: "wikilink",
+								recordId: record.id,
+								pinned: true
+							});
+						}
+					}
+					const pinCensus = {
+						resource: pinnedRecords.filter((p) => p.rung === "resource").length,
+						thread: view.view === "thread" ? pinnedRecords.filter((p) => p.rung === "thread").length : null
+					};
+					const activity = await store.listActivity({
+						scope,
+						limit: 1
+					});
+					const payload = {
+						view: view.view,
+						...view.threadId ? { threadId: view.threadId } : {},
+						nodes: nodes.map((node) => ({
+							id: node.id,
+							name: node.name,
+							kind: node.kind,
+							...node.description ? { description: node.description } : {},
+							scope: node.scope,
+							rung: deepestRung(node.scope),
+							pinned: accented.has(node.id),
+							recordCount: recordCounts.get(node.id) ?? 0,
+							createdAt: node.createdAt.toISOString(),
+							updatedAt: node.updatedAt.toISOString()
+						})),
+						edges,
+						records: graphRecords,
+						truncated,
+						outOfWindow: [...resolver.outOfWindow.values()],
+						unresolvedCapped: {
+							count: resolver.cappedCount,
+							names: resolver.cappedNames
+						},
+						pinCensus,
+						version: activity[0]?.id ?? null
+					};
+					return c.json(payload);
+				}
+			}),
+			registerApiRoute("/web/factory/projects/:id/knowledge/nodes/:nodeId", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const resolved = await this.#resolveView(loose(c));
+					if ("response" in resolved) return resolved.response;
+					const nodeId = loose(c).req.param("nodeId");
+					if (!nodeId || nodeId.length > 512) return c.json({ error: "node_not_found" }, 404);
+					const view = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
+					if (!view) return c.json({ error: "scope_not_found" }, 404);
+					const { store, scope } = view;
+					const node = await store.getNode(nodeId);
+					if (!node?.scope || !isKnowledgeScopeVisible(node.scope, scope)) return c.json({ error: "node_not_found" }, 404);
+					const pinnedNodeIds = await this.#pinnedNodeIds(view);
+					const pinnedNodeIdSet = new Set(pinnedNodeIds.map((p) => p.id));
+					const [owned, mentioning] = await Promise.all([store.listKnowledgeAbout({
+						node: node.id,
+						scope,
+						limit: 200
+					}), store.listKnowledgeMentioning({
+						node: node.id,
+						scope,
+						limit: 200
+					})]);
+					const seen = /* @__PURE__ */ new Set();
+					const records = [];
+					const push = (record, relation) => {
+						if (seen.has(record.id)) return;
+						seen.add(record.id);
+						records.push({
+							id: record.id,
+							node: record.node,
+							relation,
+							text: record.text,
+							scope: record.scope,
+							rung: deepestRung(record.scope),
+							sourceThreadId: record.sourceThreadId,
+							capturedAt: record.capturedAt.toISOString(),
+							...record.when ? { when: record.when.toISOString() } : {},
+							pinned: pinnedNodeIdSet.has(record.node),
+							...record.metadata ? { metadata: record.metadata } : {}
+						});
+					};
+					for (const record of [...owned.records].sort((a, b) => b.id.localeCompare(a.id))) push(record, "owned");
+					for (const record of [...mentioning.records].sort((a, b) => b.id.localeCompare(a.id))) push(record, "mentions");
+					const payload = {
+						node: {
+							id: node.id,
+							name: node.name,
+							kind: node.kind,
+							content: node.content ?? "",
+							...node.description ? { description: node.description } : {},
+							scope: node.scope,
+							rung: deepestRung(node.scope),
+							createdAt: node.createdAt.toISOString(),
+							updatedAt: node.updatedAt.toISOString()
+						},
+						records
+					};
+					return c.json(payload);
+				}
+			}),
+			registerApiRoute("/web/factory/projects/:id/knowledge/activity", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const resolved = await this.#resolveView(loose(c));
+					if ("response" in resolved) return resolved.response;
+					const scopeNodeId = loose(c).req.query("scopeNodeId");
+					let view;
+					let memberIds;
+					let membersTruncated = false;
+					if (scopeNodeId !== void 0) {
+						if (!UUID_RE.test(scopeNodeId)) return c.json({ error: "scope_not_found" }, 404);
+						let scopeNode;
+						try {
+							scopeNode = await findOrgScopeNode(resolved.store, resolved.orgId, scopeNodeId);
+						} catch (error) {
+							if (error instanceof KnowledgeUnsupportedCapabilityError) return c.json({ error: "scope_not_found" }, 404);
+							throw error;
+						}
+						if (!scopeNode) return c.json({ error: "scope_not_found" }, 404);
+						const { members, hasMore } = await resolved.store.listScopeMembers({
+							scopeNodeId,
+							limit: this.#limits.maxNodes
+						});
+						membersTruncated = hasMore || members.length > this.#limits.maxNodes;
+						memberIds = new Set(members.slice(0, this.#limits.maxNodes).filter((member) => !member.isScope).map((member) => member.id));
+						view = resolved;
+					} else {
+						const selected = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
+						if (!selected) return c.json({ error: "scope_not_found" }, 404);
+						view = selected;
+					}
+					const cursor = loose(c).req.query("cursor");
+					if (cursor && cursor.length > 128) return c.json({ error: "invalid_activity_cursor" }, 400);
+					const { items: activity, scanCursor } = await this.#visibleActivity(view, memberIds, cursor, 26);
+					const visiblePage = activity.slice(0, ACTIVITY_PAGE_SIZE);
+					const lastVisible = visiblePage.at(-1);
+					const payload = {
+						events: visiblePage.map(({ event, node }) => {
+							const rung = deepestRung(node.scope);
+							const threadId = rung === "thread" ? node.scope.find((address) => address.startsWith("thread:"))?.slice(7) : void 0;
+							return {
+								id: event.id,
+								action: event.action,
+								recordType: event.recordType,
+								...event.recordType === "record" ? { recordId: event.recordId } : {},
+								scope: event.scope,
+								node: {
+									id: node.id,
+									name: node.name,
+									rung,
+									...threadId ? { threadId } : {}
+								},
+								createdAt: event.createdAt.toISOString()
+							};
+						}),
+						...activity.length > ACTIVITY_PAGE_SIZE && lastVisible ? { nextCursor: lastVisible.event.id } : scanCursor ? { nextCursor: scanCursor } : {},
+						...membersTruncated ? { truncated: true } : {}
+					};
+					return c.json(payload);
+				}
+			})
+		];
+	}
+	/**
+	* Newest-first activity page where EVERY returned event targets a node
+	* visible in the view. Visibility is decided BEFORE window shaping: hidden
+	* rows are skipped entirely (no action/type/id/time metadata leaks) and a
+	* hidden backlog can never displace visible events from the window.
+	* When the scan cap stops the walk before the stream ends, `scanCursor` is
+	* the last scanned event so the caller can continue past hidden rows.
+	*/
+	async #visibleActivity(view, memberIds, cursor, limit) {
+		const out = [];
+		const nodes = /* @__PURE__ */ new Map();
+		const getNode = (id) => {
+			let node = nodes.get(id);
+			if (!node) {
+				node = view.store.getNode(id);
+				nodes.set(id, node);
+			}
+			return node;
+		};
+		let after = cursor;
+		let scanned = 0;
+		let exhausted = false;
+		while (out.length < limit && scanned < ACTIVITY_SCAN_CAP) {
+			const batch = await view.store.listActivity({
+				scope: view.scope,
+				after,
+				limit: ACTIVITY_BATCH
+			});
+			if (batch.length === 0) {
+				exhausted = true;
+				break;
+			}
+			for (const event of batch) {
+				after = event.id;
+				scanned += 1;
+				let targetNode;
+				if (event.recordType === "node") targetNode = await getNode(event.recordId);
+				else {
+					const record = await view.store.getKnowledge({ id: event.recordId });
+					targetNode = record ? await getNode(record.node) : null;
+					if (record && !isKnowledgeScopeVisible(record.scope, view.scope)) targetNode = null;
+				}
+				if (targetNode?.scope && isKnowledgeScopeVisible(targetNode.scope, view.scope) && (memberIds === void 0 || memberIds.has(targetNode.id))) out.push({
+					event,
+					node: targetNode
+				});
+				if (out.length >= limit || scanned >= ACTIVITY_SCAN_CAP) break;
+			}
+		}
+		return {
+			items: out,
+			...!exhausted && out.length < limit && scanned >= ACTIVITY_SCAN_CAP && after ? { scanCursor: after } : {}
+		};
+	}
+};
+//#endregion
+export { KnowledgeRoutes };
+
+//# sourceMappingURL=knowledge.js.map