XY-830: [ELF knowledge P1] Add knowledge page lint plus viewer and search integration

apps/elf-api/src/routes.rs

@@ -53,17 +53,18 @@ use elf_service::{
 	EventMessage, GranteeKind, GraphQueryEntityRef, GraphQueryPredicateRef, GraphQueryRequest,
 	GraphQueryResponse, IngestionProfileSelector, KnowledgePageGetRequest,
 	KnowledgePageLintRequest, KnowledgePageLintResponse, KnowledgePageRebuildRequest,
-	KnowledgePageRebuildResponse, KnowledgePageResponse, KnowledgePagesListRequest,
-	KnowledgePagesListResponse, ListRequest, ListResponse, NoteFetchRequest, NoteFetchResponse,
-	NoteProvenanceBundleResponse, NoteProvenanceGetRequest, PayloadLevel, PublishNoteRequest,
-	QueryPlan, RankingRequestOverride, RebuildReport, SearchDetailsRequest, SearchDetailsResult,
-	SearchExplainRequest, SearchExplainResponse, SearchIndexItem, SearchRequest, SearchResponse,
-	SearchSessionGetRequest, SearchTimelineGroup, SearchTimelineRequest, SearchTrajectoryResponse,
-	SearchTrajectorySummary, ShareScope, SpaceGrantRevokeRequest, SpaceGrantRevokeResponse,
-	SpaceGrantUpsertRequest, SpaceGrantsListRequest, TextPositionSelector, TextQuoteSelector,
-	TraceBundleGetRequest, TraceBundleResponse, TraceGetRequest, TraceGetResponse,
-	TraceRecentListRequest, TraceRecentListResponse, TraceTrajectoryGetRequest,
-	UnpublishNoteRequest, UpdateRequest, UpdateResponse, search::TraceBundleMode,
+	KnowledgePageRebuildResponse, KnowledgePageResponse, KnowledgePageSearchRequest,
+	KnowledgePageSearchResponse, KnowledgePagesListRequest, KnowledgePagesListResponse,
+	ListRequest, ListResponse, NoteFetchRequest, NoteFetchResponse, NoteProvenanceBundleResponse,
+	NoteProvenanceGetRequest, PayloadLevel, PublishNoteRequest, QueryPlan, RankingRequestOverride,
+	RebuildReport, SearchDetailsRequest, SearchDetailsResult, SearchExplainRequest,
+	SearchExplainResponse, SearchIndexItem, SearchRequest, SearchResponse, SearchSessionGetRequest,
+	SearchTimelineGroup, SearchTimelineRequest, SearchTrajectoryResponse, SearchTrajectorySummary,
+	ShareScope, SpaceGrantRevokeRequest, SpaceGrantRevokeResponse, SpaceGrantUpsertRequest,
+	SpaceGrantsListRequest, TextPositionSelector, TextQuoteSelector, TraceBundleGetRequest,
+	TraceBundleResponse, TraceGetRequest, TraceGetResponse, TraceRecentListRequest,
+	TraceRecentListResponse, TraceTrajectoryGetRequest, UnpublishNoteRequest, UpdateRequest,
+	UpdateResponse, search::TraceBundleMode,
 };
 
 /// JSON OpenAPI contract route.
@@ -138,6 +139,7 @@ const VIEWER_HTML: &str = include_str!("../static/viewer.html");
 		consolidation_proposal_review,
 		knowledge_page_rebuild,
 		knowledge_pages_list,
+		knowledge_pages_search,
 		knowledge_page_get,
 		knowledge_page_lint,
 		rebuild_qdrant,
@@ -393,6 +395,13 @@ struct KnowledgePagesListQuery {
 	limit: Option<u32>,
 }
 
+#[derive(Clone, Debug, Deserialize)]
+struct KnowledgePagesSearchBody {
+	query: String,
+	page_kind: Option<KnowledgePageKind>,
+	limit: Option<u32>,
+}
+
 #[derive(Clone, Debug, Serialize, ToSchema)]
 struct AdminIngestionProfileDefaultResponseV2 {
 	profile_id: String,
@@ -678,6 +687,7 @@ pub fn admin_router(state: AppState) -> Router {
 		)
 		.route("/v2/admin/knowledge/pages", routing::get(knowledge_pages_list))
 		.route("/v2/admin/knowledge/pages/rebuild", routing::post(knowledge_page_rebuild))
+		.route("/v2/admin/knowledge/pages/search", routing::post(knowledge_pages_search))
 		.route("/v2/admin/knowledge/pages/{page_id}", routing::get(knowledge_page_get))
 		.route("/v2/admin/knowledge/pages/{page_id}/lint", routing::post(knowledge_page_lint))
 		.route("/v2/admin/qdrant/rebuild", routing::post(rebuild_qdrant))
@@ -2795,6 +2805,45 @@ async fn knowledge_pages_list(
 	Ok(Json(response))
 }
 
+#[utoipa::path(
+	post,
+	path = "/v2/admin/knowledge/pages/search",
+	tag = "knowledge",
+	request_body = Value,
+	responses(
+		(status = 200, description = "Knowledge page section search results.", body = Value),
+		(status = 400, description = "Invalid request.", body = ErrorBody),
+		(status = 401, description = "Authentication required.", body = ErrorBody),
+		(status = 403, description = "Admin access required.", body = ErrorBody),
+		(status = 422, description = "Non-English input rejected.", body = ErrorBody),
+		(status = 500, description = "Internal error.", body = ErrorBody),
+	)
+)]
+async fn knowledge_pages_search(
+	State(state): State<AppState>,
+	headers: HeaderMap,
+	payload: Result<Json<KnowledgePagesSearchBody>, JsonRejection>,
+) -> Result<Json<KnowledgePageSearchResponse>, ApiError> {
+	let ctx = RequestContext::from_headers(&headers)?;
+	let Json(payload) = payload.map_err(|err| {
+		tracing::warn!(error = %err, "Invalid request payload.");
+
+		json_error(StatusCode::BAD_REQUEST, "INVALID_REQUEST", "Invalid request payload.", None)
+	})?;
+	let response = state
+		.service
+		.knowledge_pages_search(KnowledgePageSearchRequest {
+			tenant_id: ctx.tenant_id,
+			project_id: ctx.project_id,
+			query: payload.query,
+			page_kind: payload.page_kind,
+			limit: payload.limit,
+		})
+		.await?;
+
+	Ok(Json(response))
+}
+
 #[utoipa::path(
 	get,
 	path = "/v2/admin/knowledge/pages/{page_id}",
@@ -3451,12 +3500,15 @@ mod tests {
 		assert!(html.contains("/v2/admin/traces/recent"));
 		assert!(html.contains("/v2/admin/traces/${encodeURIComponent(traceId)}/bundle"));
 		assert!(html.contains("/v2/admin/notes/"));
+		assert!(html.contains("/v2/admin/knowledge/pages/search"));
 		assert!(html.contains("mode: \"full\""));
 		assert!(html.contains("candidates_limit: 200"));
 		assert!(html.contains("Replay Candidates"));
 		assert!(html.contains("Selected Final Results"));
 		assert!(html.contains("Providers And Ranking"));
 		assert!(html.contains("Relation Context"));
+		assert!(html.contains("Knowledge Page Snippets"));
+		assert!(html.contains("Derived page: source notes"));
 		assert!(html.contains("directTraceId"));
 		assert!(html.contains("trace_id"));
 		assert!(html.contains("loadInitialTrace"));

apps/elf-api/static/viewer.html

@@ -358,6 +358,12 @@
 			color: var(--amber);
 		}
 
+		.chip.danger {
+			background: #fff1f0;
+			border-color: #efb4b1;
+			color: var(--danger);
+		}
+
 		.kv {
 			border: 1px solid var(--line);
 			border-radius: 8px;
@@ -630,12 +636,25 @@ <h2>Timeline</h2>
 									<div id="timelineResults" class="list"><div class="empty">No timeline loaded.</div></div>
 								</div>
 							</div>
+							<div class="panel">
+								<div class="panel-head">
+									<h2>Knowledge Page Snippets</h2>
+									<button type="button" id="searchKnowledgeButton">Search Pages</button>
+								</div>
+								<div class="panel-body">
+									<div id="knowledgeResults" class="list"><div class="empty">Run a search to load derived page snippets.</div></div>
+								</div>
+							</div>
 						</div>
 						<div class="split-stack">
 							<div class="panel">
 								<div class="panel-head"><h2>Note Detail</h2></div>
 								<div class="panel-body" id="noteDetail"><div class="empty">Select a note.</div></div>
 							</div>
+							<div class="panel">
+								<div class="panel-head"><h2>Knowledge Page Detail</h2></div>
+								<div class="panel-body" id="knowledgeDetail"><div class="empty">Select a derived page snippet.</div></div>
+							</div>
 							<div class="panel">
 								<div class="panel-head"><h2>Trace Explain</h2></div>
 								<div class="panel-body" id="traceDetail"><div class="empty">Run or load a session.</div></div>
@@ -747,6 +766,7 @@ <h2>Recent Traces</h2>
 			activeTab: "searchView",
 			session: null,
 			selectedNoteId: null,
+			selectedKnowledgePageId: null,
 			traceBundle: null,
 			traceMetrics: {}
 		};
@@ -1034,6 +1054,161 @@ <h2>Recent Traces</h2>
 			target.replaceChildren(...session.items.map((item) => resultRow(item, item.note_id === state.selectedNoteId)));
 		}
 
+		function trustChipVariant(trustState) {
+			if (trustState === "derived_error") {
+				return "danger";
+			}
+			if (trustState === "derived_warning" || trustState === "derived_low_coverage") {
+				return "amber";
+			}
+			return "teal";
+		}
+
+		function knowledgeResultRow(item, selected = false) {
+			const openButton = make("button", { type: "button", text: "Open Page" });
+			openButton.addEventListener("click", (event) => {
+				event.stopPropagation();
+				openKnowledgePage(item.page_id);
+			});
+			const row = make("div", {
+				className: `row clickable ${selected ? "selected" : ""}`.trim(),
+				dataPageId: item.page_id
+			}, [
+				make("div", { className: "row-head" }, [
+					make("div", { className: "title", text: `${item.title} / ${item.heading}` }),
+					openButton
+				]),
+				make("div", { className: "chips" }, [
+					chip("derived page", "indigo"),
+					chip(item.page_kind, "teal"),
+					chip(item.trust_state || "derived", trustChipVariant(item.trust_state)),
+					chip(`citations ${item.citation_count ?? 0}`),
+					chip(`sources ${item.source_ref_count ?? 0}`)
+				]),
+				make("div", { className: "summary", text: item.snippet || "" }),
+				item.repair_guidance ? make("div", { className: "summary", text: item.repair_guidance }) : make("span")
+			]);
+			row.addEventListener("click", () => openKnowledgePage(item.page_id));
+			return row;
+		}
+
+		function renderKnowledgeResults(items) {
+			const target = $("#knowledgeResults");
+			if (!items || items.length === 0) {
+				target.replaceChildren(empty("No derived page snippets matched."));
+				return;
+			}
+			target.replaceChildren(...items.map((item) => knowledgeResultRow(item, item.page_id === state.selectedKnowledgePageId)));
+		}
+
+		async function searchKnowledgePages(queryOverride) {
+			const query = (queryOverride || $("#searchQuery").value).trim();
+			if (!query) {
+				$("#knowledgeResults").replaceChildren(empty("Query is required."));
+				return;
+			}
+			try {
+				const data = await api("/v2/admin/knowledge/pages/search", {
+					method: "POST",
+					body: JSON.stringify({
+						query,
+						limit: Number($("#topK").value || 12)
+					})
+				});
+				renderKnowledgeResults(data.items || []);
+			} catch (err) {
+				$("#knowledgeResults").replaceChildren(empty(err.message));
+			}
+		}
+
+		async function openKnowledgePage(pageId) {
+			if (!pageId) {
+				return;
+			}
+			state.selectedKnowledgePageId = pageId;
+			document.querySelectorAll("#knowledgeResults [data-page-id]").forEach((row) => {
+				row.classList.toggle("selected", row.dataset.pageId === pageId);
+			});
+			if (state.session) {
+				renderSearchSession(state.session);
+			}
+			setStatus(`Loading knowledge page ${pageId}...`);
+			try {
+				const page = await api(`/v2/admin/knowledge/pages/${encodeURIComponent(pageId)}`);
+				renderKnowledgePageDetail($("#knowledgeDetail"), page);
+				setStatus(`Loaded knowledge page ${pageId}.`);
+			} catch (err) {
+				setStatus(err.message, true);
+				$("#knowledgeDetail").replaceChildren(empty(err.message));
+			}
+		}
+
+		function renderKnowledgePageDetail(target, data) {
+			if (!data || !data.page) {
+				target.replaceChildren(empty("Knowledge page unavailable."));
+				return;
+			}
+			const page = data.page;
+			const lint = data.lint_findings || [];
+			target.replaceChildren(
+				kvTable([
+					["page_id", page.page_id],
+					["kind / key", `${page.page_kind} / ${page.page_key}`],
+					["status", page.status],
+					["updated_at", dateText(page.updated_at)],
+					["rebuilt_at", dateText(page.rebuilt_at)],
+					["derived notice", "Derived page: source notes, events, relations, and proposals remain authoritative."]
+				]),
+				make("div", { className: "split-stack", style: "margin-top: 12px;" }, [
+					make("div", { className: "title", text: "Source coverage" }),
+					pre(page.source_coverage || {}),
+					make("div", { className: "title", text: "Sections" }),
+					...(data.sections || []).map(knowledgeSectionRow),
+					make("div", { className: "title", text: "Lint findings" }),
+					lint.length ? make("div", { className: "list" }, lint.map(lintFindingRow)) : empty("No lint findings stored."),
+					make("div", { className: "title", text: "Normalized source refs" }),
+					sourceRefsTable(data.source_refs || [])
+				])
+			);
+		}
+
+		function knowledgeSectionRow(sectionItem) {
+			return section(sectionItem.heading || sectionItem.section_key, [
+				make("div", { className: "chips" }, [
+					chip(sectionItem.role || "section"),
+					chip(`citations ${sectionItem.citation_count ?? 0}`),
+					chip(`source refs ${sectionItem.source_ref_count ?? 0}`),
+					chip(sectionItem.coverage_complete ? "coverage complete" : "coverage incomplete", sectionItem.coverage_complete ? "teal" : "amber")
+				]),
+				pre(sectionItem.content || ""),
+				sourceRefsTable(sectionItem.source_backlinks || [])
+			]);
+		}
+
+		function lintFindingRow(finding) {
+			return make("div", { className: "row" }, [
+				make("div", { className: "row-head" }, [
+					make("div", { className: "title", text: finding.finding_type }),
+					chip(finding.severity, finding.severity === "error" ? "danger" : "amber")
+				]),
+				make("div", { className: "summary", text: finding.message || "" }),
+				make("div", { className: "summary", text: finding.repair_guidance || "" }),
+				pre(finding.details || {})
+			]);
+		}
+
+		function sourceRefsTable(refs) {
+			if (!refs || refs.length === 0) {
+				return empty("No source refs.");
+			}
+			return table(["kind", "source_id", "status", "updated"], refs.map((ref) => [
+				ref.source_kind,
+				{ value: ref.source_id, wrap: true },
+				ref.source_status || "none",
+				dateText(ref.source_updated_at)
+			]));
+		}
+
 		async function runSearch() {
 			const query = $("#searchQuery").value.trim();
 			if (!query) {
@@ -1060,7 +1235,8 @@ <h2>Recent Traces</h2>
 				$("#loadSearchId").value = session.search_id;
 				await Promise.all([
 					loadTimeline(),
-					loadTraceBundle(session.trace_id, $("#traceDetail"))
+					loadTraceBundle(session.trace_id, $("#traceDetail")),
+					searchKnowledgePages(query)
 				]);
 				if (state.selectedNoteId) {
 					await selectSearchNote(state.selectedNoteId);
@@ -1086,7 +1262,8 @@ <h2>Recent Traces</h2>
 				renderSearchSession(session);
 				await Promise.all([
 					loadTimeline(),
-					loadTraceBundle(session.trace_id, $("#traceDetail"))
+					loadTraceBundle(session.trace_id, $("#traceDetail")),
+					searchKnowledgePages()
 				]);
 				if (state.selectedNoteId) {
 					await selectSearchNote(state.selectedNoteId);
@@ -1535,6 +1712,8 @@ <h2>Recent Traces</h2>
 			if (state.activeTab === "searchView") {
 				if (state.session) {
 					await loadSession();
+				} else {
+					await searchKnowledgePages();
 				}
 			} else if (state.activeTab === "notesView") {
 				await loadNotes();
@@ -1554,6 +1733,7 @@ <h2>Recent Traces</h2>
 			$("#runSearchButton").addEventListener("click", runSearch);
 			$("#loadSessionButton").addEventListener("click", loadSession);
 			$("#loadTimelineButton").addEventListener("click", loadTimeline);
+			$("#searchKnowledgeButton").addEventListener("click", () => searchKnowledgePages());
 			$("#loadNotesButton").addEventListener("click", loadNotes);
 			$("#loadTracesButton").addEventListener("click", loadRecentTraces);
 			$("#loadTraceByIdButton").addEventListener("click", loadTraceById);

apps/elf-api/tests/http.rs

@@ -852,6 +852,7 @@ async fn openapi_json_route_serves_generated_contract() {
 	assert_openapi_method(&spec, "/v2/admin/consolidation/proposals/{proposal_id}/review", "post");
 	assert_openapi_method(&spec, "/v2/admin/knowledge/pages/rebuild", "post");
 	assert_openapi_method(&spec, "/v2/admin/knowledge/pages", "get");
+	assert_openapi_method(&spec, "/v2/admin/knowledge/pages/search", "post");
 	assert_openapi_method(&spec, "/v2/admin/knowledge/pages/{page_id}", "get");
 	assert_openapi_method(&spec, "/v2/admin/knowledge/pages/{page_id}/lint", "post");
 }
@@ -880,6 +881,7 @@ async fn scalar_docs_route_serves_api_reference_html() {
 	assert!(html.contains("/v2/admin/events/ingestion-profiles/default"));
 	assert!(html.contains("/v2/admin/consolidation/proposals"));
 	assert!(html.contains("/v2/admin/knowledge/pages"));
+	assert!(html.contains("/v2/admin/knowledge/pages/search"));
 }
 
 #[tokio::test]

docs/spec/real_world_agent_memory_benchmark_v1.md

@@ -312,7 +312,7 @@ is not a hidden unsupported claim because the page explicitly marks the gap.
 Each `lint_findings[]` entry SHOULD include:
 
 - `finding_id`
-- `finding_type`: for example `stale_claim`, `unsupported_section`, or
+- `finding_type`: for example `stale_claim`, `unsupported_claim`, or
   `contradiction`.
 - `severity`
 - `text`