@obsunified/collector 2.2.1 → 2.3.0

package/src/plugins/connected-routes.test.ts

@@ -335,7 +335,7 @@ describe("ConnectedRail manifest — span profile section (RFC 0009 #5)", () =>
 		expect(exemplarSection).toBeDefined();
 		expect(exemplarSection?.links[0].label).toContain("http.server.duration");
 		expect(exemplarSection?.links[0].href).toBe(
-			"#/traces/trace-metric#span=span-hot",
+			"#/traces?trace=trace-metric&span=span-hot",
 		);
 	});
 });
@@ -470,7 +470,7 @@ describe("ConnectedRail manifest — raw signal action back-links", () => {
 			m.down.find((s) => s.label === "Evaluations for this span")?.links[0],
 		).toMatchObject({
 			label: "eval: groundedness (passed)",
-			href: "#/evals/eval-explicit",
+			href: "#/evaluations/eval-explicit",
 		});
 		expect(
 			m.related.find((s) => s.label === "Agent runs for this span")?.links[0],
@@ -673,7 +673,7 @@ describe("ConnectedRail manifest — raw signal action back-links", () => {
 				?.links[0],
 		).toMatchObject({
 			label: "[agent.step] Fallback normalized action",
-			href: "#/actions/fallback:trace-fallback:agent.step:1",
+			href: "#/actions/fallback%3Atrace-fallback%3Aagent.step%3A1",
 			causalConfidence: ActionConfidence.Fallback,
 			source: "trace_id",
 			confidence: 0.55,
@@ -749,7 +749,7 @@ describe("ConnectedRail manifest — raw signal action back-links", () => {
 		).toMatchObject({ href: "#/tool-calls/tool-explicit" });
 		expect(
 			m.down.find((s) => s.label === "Evaluations for this AI call")?.links[0],
-		).toMatchObject({ href: "#/evals/eval-explicit" });
+		).toMatchObject({ href: "#/evaluations/eval-explicit" });
 		expect(
 			m.related.find((s) => s.label === "Agent runs for this AI call")
 				?.links[0],
@@ -831,12 +831,12 @@ describe("ConnectedRail manifest — profile source entity", () => {
 		const traceSection = m.across.find((s) => s.label === "Sampled traces");
 		expect(traceSection?.links[0]).toMatchObject({
 			label: "trace trace-prof",
-			href: "#/traces/trace-prof",
+			href: "#/traces?trace=trace-prof",
 		});
 
 		const spanSection = m.across.find((s) => s.label === "Sampled spans");
 		expect(spanSection?.links[0].href).toBe(
-			"#/traces/trace-prof#span=span-hot",
+			"#/traces?trace=trace-prof&span=span-hot",
 		);
 
 		const actionSection = m.down.find((s) =>
@@ -1108,7 +1108,9 @@ describe("ConnectedRail scenario acceptance contracts", () => {
 		const sessionSpans = sessionManifest.across.find((s) =>
 			s.label.toLowerCase().includes("span"),
 		);
-		expect(sessionSpans?.links[0].href).toBe("#/traces/trace-a#span=span-hot");
+		expect(sessionSpans?.links[0].href).toBe(
+			"#/traces?trace=trace-a&span=span-hot",
+		);
 
 		const spanManifest = await fetch(
 			"/internal/connected/span/trace-a:span-hot",
@@ -1280,7 +1282,7 @@ describe("ConnectedRail scenario acceptance contracts", () => {
 		const aiSection = userManifest.across.find((s) =>
 			s.label.toLowerCase().includes("ai call"),
 		);
-		expect(aiSection?.links[0].href).toBe("#/ai?id=ai-heavy-1");
+		expect(aiSection?.links[0].href).toBe("#/ai/calls/ai-heavy-1");
 
 		const sessionManifest = await fetch(
 			"/internal/connected/usage/sess-heavy?session_id=sess-heavy",
@@ -1289,7 +1291,7 @@ describe("ConnectedRail scenario acceptance contracts", () => {
 			s.label.toLowerCase().includes("span"),
 		);
 		expect(sessionSpans?.links[0].href).toBe(
-			"#/traces/trace-ai-heavy#span=span-llm",
+			"#/traces?trace=trace-ai-heavy&span=span-llm",
 		);
 
 		const spanManifest = await fetch(
@@ -1464,7 +1466,7 @@ describe("ConnectedRail manifest — agent action graph entities (RFC 0010)", ()
 		// OTel Trace in related
 		const relatedTrace = m.related.find((s) => s.label === "OTel Trace");
 		expect(relatedTrace).toBeDefined();
-		expect(relatedTrace?.links[0].href).toBe("#/traces/tx-789");
+		expect(relatedTrace?.links[0].href).toBe("#/traces?trace=tx-789");
 	});
 
 	it("action detail raw manifest exposes causal confidence on action refs", async () => {
@@ -1650,7 +1652,7 @@ describe("ConnectedRail manifest — agent action graph entities (RFC 0010)", ()
 		// Up has Agent
 		const agentSec = m.up.find((s) => s.label === "Agent");
 		expect(agentSec).toBeDefined();
-		expect(agentSec?.links[0].href).toBe("#/agents/my-agent");
+		expect(agentSec?.links[0].href).toBe("#/evidence?kind=agent&id=my-agent");
 
 		// Down has Actions (Decision Spine)
 		const decisionSpine = m.down.find(

package/src/plugins/connected-routes.ts

@@ -15,7 +15,7 @@
  * RFC 0006 § Connected rail / Empty-state.
  */
 
-import type { CausalProofTier } from "@obsunified/types";
+import { type CausalProofTier, dashboardRouteToHref } from "@obsunified/types";
 import { ActionConfidence } from "@obsunified/types/constants";
 import type { CollectorPlugin } from "../framework/collector";
 import { getChangeEvent } from "../lib/autosre-change-correlation";
@@ -37,11 +37,13 @@ import type {
 import type { SqlDb } from "../lib/sql-db";
 import { sqlDbFor } from "../lib/sql-db";
 import { getProjectId } from "./_context";
+import { respondWithContract } from "./autosre-routes";
 
 import {
 	type ActionContextLinkMetadata,
 	type ConnectedEntityKind,
 	type ConnectedManifest,
+	hrefForEntity,
 	KNOWN_KINDS,
 	linksFromActions,
 	linksFromAi,
@@ -59,6 +61,7 @@ import {
 	linkToTrace,
 	MAX_LINKS_INLINE,
 	profileLinksForTrace,
+	resolveFaultLocusTarget,
 } from "./connected-routes/manifest";
 
 export type {
@@ -454,7 +457,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 											? [
 													{
 														label: `${traceIds.length} sampled traces`,
-														href: `#/traces?trace=${encodeURIComponent(traceIds[0])}`,
+														href: dashboardRouteToHref({
+															tab: "traces",
+															traceId: traceIds[0],
+														}),
 														count: traceIds.length,
 														sample: traceIds[0],
 													},
@@ -554,7 +560,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 											.slice(0, MAX_LINKS_INLINE)
 											.map((toolCall) => ({
 												label: `tool: ${toolCall.tool_name}`,
-												href: `#/tool-calls/${toolCall.id}`,
+												href: dashboardRouteToHref({
+													tab: "tool-calls",
+													toolCallId: toolCall.id,
+												}),
 												entityKind: "tool_call",
 												entityId: toolCall.id,
 												...traceLevelMetadata("profile tool call"),
@@ -984,7 +993,7 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							links: [
 								{
 									label: `${run.agentName} (v${run.agentVersion})`,
-									href: `#/agents/${run.agentId}`,
+									href: hrefForEntity("agent", run.agentId),
 								},
 							],
 						},
@@ -1068,7 +1077,7 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							links: [
 								{
 									label: `${changeRow.targetNodeId} (${changeRow.environment})`,
-									href: `#/health?node=${encodeURIComponent(changeRow.targetNodeId)}`,
+									...resolveFaultLocusTarget(changeRow.targetNodeId),
 									relationshipCertainty: "exact",
 									reason: "Target node mutated by this change event.",
 								},
@@ -1097,7 +1106,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							label: "Attributed Findings",
 							links: findings.results.map((f) => ({
 								label: f.title,
-								href: `#/findings/${encodeURIComponent(f.id)}`,
+								href: dashboardRouteToHref({
+									tab: "findings",
+									findingId: f.id,
+								}),
 								entityKind: "finding",
 								entityId: f.id,
 								relationshipCertainty: "exact",
@@ -1115,10 +1127,11 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 					const spans = changeRow.version
 						? await db
 								.prepare(
-									`SELECT DISTINCT trace_id, span_id, service_name, span_name
+									`SELECT trace_id, span_id, service_name, span_name
 									 FROM telemetry_spans
 									 WHERE project_id = ? AND environment = ? AND service_version = ? AND status_code = 2
-									 ORDER BY start_time DESC LIMIT 5`,
+									 GROUP BY trace_id, span_id, service_name, span_name
+									 ORDER BY MAX(start_time) DESC LIMIT 5`,
 								)
 								.bind(projectId, changeRow.environment, changeRow.version)
 								.all<{
@@ -1134,7 +1147,11 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							label: "Failing Spans on Cohort Version",
 							links: spans.results.map((s) => ({
 								label: `${s.service_name} · ${s.span_name}`,
-								href: `#/traces/${s.trace_id}#span=${s.span_id}`,
+								href: dashboardRouteToHref({
+									tab: "traces",
+									traceId: s.trace_id,
+									spanId: s.span_id,
+								}),
 								entityKind: "span",
 								entityId: `${s.trace_id}:${s.span_id}`,
 								relationshipCertainty: "exact",
@@ -1164,7 +1181,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							links: [
 								{
 									label: `incident ${findingRow.incidentId}`,
-									href: `#/incidents/${encodeURIComponent(findingRow.incidentId)}`,
+									href: dashboardRouteToHref({
+										tab: "incidents",
+										incidentId: findingRow.incidentId,
+									}),
 									entityKind: "incident",
 									entityId: findingRow.incidentId,
 									relationshipCertainty: "exact",
@@ -1179,7 +1199,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							links: [
 								{
 									label: `change ${findingRow.contributingChangeId}`,
-									href: `#/changes/${encodeURIComponent(findingRow.contributingChangeId)}`,
+									href: dashboardRouteToHref({
+										tab: "changes",
+										changeId: findingRow.contributingChangeId,
+									}),
 									entityKind: "change",
 									entityId: findingRow.contributingChangeId,
 									relationshipCertainty: "exact",
@@ -1195,7 +1218,7 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							links: [
 								{
 									label: `fault locus: ${findingRow.faultLocusEntityId}`,
-									href: `#/traces?q=${encodeURIComponent(findingRow.faultLocusEntityId)}`,
+									...resolveFaultLocusTarget(findingRow.faultLocusEntityId),
 									relationshipCertainty: "exact",
 									causalProofTier: proofTier,
 								},
@@ -1203,7 +1226,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 									? [
 											{
 												label: `contending trace ${findingRow.contendingTraceId}`,
-												href: `#/traces/${encodeURIComponent(findingRow.contendingTraceId)}`,
+												href: dashboardRouteToHref({
+													tab: "traces",
+													traceId: findingRow.contendingTraceId,
+												}),
 												entityKind: "trace" as const,
 												entityId: findingRow.contendingTraceId,
 												relationshipCertainty: "inferred" as const,
@@ -1249,11 +1275,11 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							links: [
 								{
 									label: `${incRow.symptomAnchorKind}: ${incRow.symptomAnchorId}`,
-									href: `#/alerts?id=${encodeURIComponent(incRow.symptomAnchorId)}`,
-									entityKind:
-										incRow.symptomAnchorKind === "analysis"
-											? "analysis"
-											: "alert",
+									href: hrefForEntity(
+										incRow.symptomAnchorKind,
+										incRow.symptomAnchorId,
+									),
+									entityKind: incRow.symptomAnchorKind,
 									entityId: incRow.symptomAnchorId,
 									relationshipCertainty: "exact",
 								},
@@ -1277,7 +1303,10 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 							label: "Findings",
 							links: incFindings.results.map((f) => ({
 								label: f.title,
-								href: `#/findings/${encodeURIComponent(f.id)}`,
+								href: dashboardRouteToHref({
+									tab: "findings",
+									findingId: f.id,
+								}),
 								entityKind: "finding" as const,
 								entityId: f.id,
 								relationshipCertainty: "exact" as const,
@@ -1347,7 +1376,11 @@ export const connectedRoutesPlugin: CollectorPlugin = {
 				];
 			}
 
-			return c.json(manifest);
+			return respondWithContract(
+				c,
+				"GET /internal/connected/:kind/:id",
+				manifest,
+			);
 		});
 	},
 };

package/src/plugins/eval-cases-routes.ts

@@ -3,7 +3,10 @@ import type {
 	EvidenceReferenceContract as EvidenceReferenceContractType,
 	JsonValue,
 } from "@obsunified/types";
-import { EVIDENCE_REFERENCE_CONTRACT } from "@obsunified/types";
+import {
+	dashboardRouteToHref,
+	EVIDENCE_REFERENCE_CONTRACT,
+} from "@obsunified/types";
 import type { CollectorPlugin } from "../framework/collector";
 import {
 	type EvalCase,
@@ -20,6 +23,7 @@ import { randomHex } from "../lib/hash";
 import { sqlDbFor } from "../lib/sql-db";
 import { getProjectId } from "./_context";
 import { readJsonObject } from "./_json";
+import { respondWithContract } from "./autosre-routes";
 
 interface EvalCaseRequestBody {
 	sourceEntityType?: unknown;
@@ -122,7 +126,10 @@ const evalCaseResultEvidenceReferences = (
 			sourceLabel: `Eval case result "${resultId}"`,
 			sourceId: resultId,
 			sourceKind: "eval_case_result",
-			sourceRoute: `#/evaluations?case=${encodeURIComponent(evalCase.id)}&result=${encodeURIComponent(resultId)}`,
+			sourceRoute: dashboardRouteToHref({
+				tab: "evaluations",
+				evaluationId: evalCase.id,
+			}),
 			sourceName: evalCase.name,
 		},
 		evalCase,
@@ -189,7 +196,12 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 			const store = new EvalCasesStore(sqlDbFor(c.env));
 			try {
 				const evalCase = await store.createCase(getProjectId(c), input);
-				return c.json({ evalCase }, 201);
+				return respondWithContract(
+					c,
+					"POST /internal/eval-cases",
+					{ evalCase },
+					201,
+				);
 			} catch (err) {
 				if (err instanceof EvalCaseSourceNotFoundError) {
 					return c.json(
@@ -223,7 +235,7 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 				sourceEntityId: c.req.query("sourceEntityId"),
 				limit: parseLimit(c.req.query("limit")),
 			});
-			return c.json({ evalCases });
+			return respondWithContract(c, "GET /internal/eval-cases", { evalCases });
 		});
 
 		app.get("/internal/eval-cases/:id", async (c) => {
@@ -237,7 +249,9 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 					404,
 				);
 			}
-			return c.json({ evalCase });
+			return respondWithContract(c, "GET /internal/eval-cases/:id", {
+				evalCase,
+			});
 		});
 
 		app.post("/internal/eval-runs", async (c) => {
@@ -349,7 +363,12 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 			const store = new EvalCasesStore(sqlDbFor(c.env));
 			try {
 				const evalRun = await store.createRun(getProjectId(c), input);
-				return c.json({ evalRun }, 201);
+				return respondWithContract(
+					c,
+					"POST /internal/eval-runs",
+					{ evalRun },
+					201,
+				);
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
 				if (message.includes("does not reference a case")) {
@@ -377,7 +396,7 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 				status,
 				limit: parseLimit(c.req.query("limit")),
 			});
-			return c.json({ evalRuns });
+			return respondWithContract(c, "GET /internal/eval-runs", { evalRuns });
 		});
 
 		app.get("/internal/eval-runs/:id", async (c) => {
@@ -391,7 +410,7 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 					404,
 				);
 			}
-			return c.json({ evalRun });
+			return respondWithContract(c, "GET /internal/eval-runs/:id", { evalRun });
 		});
 
 		app.post("/internal/eval-cases/:id/results", async (c) => {
@@ -503,7 +522,9 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 				evidenceContract: EVIDENCE_REFERENCE_CONTRACT,
 			};
 
-			return c.json(
+			return respondWithContract(
+				c,
+				"POST /internal/eval-cases/:id/results",
 				{
 					evalCaseResult,
 					evalRun: refreshedRun,
@@ -569,7 +590,9 @@ export const evalCasesRoutesPlugin: CollectorPlugin = {
 				}),
 			);
 
-			return c.json({ evalCaseResults });
+			return respondWithContract(c, "GET /internal/eval-cases/:id/results", {
+				evalCaseResults,
+			});
 		});
 	},
 };

package/src/plugins/evidence-retrieval-routes.ts

@@ -11,6 +11,10 @@ import type {
 	TelemetrySpanDetail,
 	TelemetryTraceDetailResponse,
 } from "@obsunified/types";
+import {
+	buildFindingFingerprint,
+	dashboardRouteToHref,
+} from "@obsunified/types";
 import type { CollectorPlugin } from "../framework/collector";
 import {
 	computeChangeBlastRadius,
@@ -18,6 +22,7 @@ import {
 	listChangeEvents,
 } from "../lib/autosre-change-correlation";
 import {
+	fingerprintInputFromSpan,
 	getInvestigationFinding,
 	searchInvestigationFindings,
 } from "../lib/autosre-findings";
@@ -39,6 +44,7 @@ import { LogsStore } from "../lib/logs-store";
 import { decodePprofBlob, summarizeProfileFrames } from "../lib/parse-pprof";
 import type { SqlDb } from "../lib/sql-db";
 import { getProjectId } from "./_context";
+import { respondWithContract } from "./autosre-routes";
 import { fetchReplayChunks } from "./replay-query-routes";
 
 interface EvidenceRefPayload {
@@ -156,24 +162,35 @@ const estimateTokens = (value: unknown): number =>
 	Math.ceil(JSON.stringify(value).length / 4);
 
 const traceRoute = (traceId: string) =>
-	`#/traces/${encodeURIComponent(traceId)}`;
+	dashboardRouteToHref({ tab: "traces", traceId });
 const spanRoute = (traceId: string, spanId: string) =>
-	`${traceRoute(traceId)}#span=${encodeURIComponent(spanId)}`;
-const logRoute = (logId: string) => `#/logs?id=${encodeURIComponent(logId)}`;
+	dashboardRouteToHref({ tab: "traces", traceId, spanId });
+const logRoute = (logId: string) =>
+	dashboardRouteToHref({ tab: "logs", logId });
 const actionRoute = (actionId: string) =>
-	`#/actions/${encodeURIComponent(actionId)}`;
+	dashboardRouteToHref({ tab: "actions", actionId });
 const agentRunRoute = (agentRunId: string) =>
-	`#/agent-runs/${encodeURIComponent(agentRunId)}`;
+	dashboardRouteToHref({ tab: "agent-runs", agentRunId });
 const toolCallRoute = (toolCallId: string) =>
-	`#/tool-calls/${encodeURIComponent(toolCallId)}`;
+	dashboardRouteToHref({ tab: "tool-calls", toolCallId });
 const replayRoute = (sessionId: string) =>
-	`#/replay?session=${encodeURIComponent(sessionId)}`;
+	dashboardRouteToHref({ tab: "replay", sessionId });
 const profileRoute = (profileId: string, traceId?: string) =>
-	`#/profiles/${encodeURIComponent(profileId)}${
-		traceId ? `?trace_id=${encodeURIComponent(traceId)}` : ""
-	}`;
+	dashboardRouteToHref({
+		tab: "profiles",
+		profileId,
+		...(traceId ? { traceId } : {}),
+	});
 const aiCallRoute = (callId: string) =>
-	`#/ai/calls/${encodeURIComponent(callId)}`;
+	dashboardRouteToHref({ tab: "ai", aiCallId: callId });
+const evalRoute = (evaluationId: string) =>
+	dashboardRouteToHref({ tab: "evaluations", evaluationId });
+const changeEntityRoute = (changeId: string) =>
+	dashboardRouteToHref({ tab: "changes", changeId });
+const findingEntityRoute = (findingId: string) =>
+	dashboardRouteToHref({ tab: "findings", findingId });
+const incidentEntityRoute = (incidentId: string) =>
+	dashboardRouteToHref({ tab: "incidents", incidentId });
 
 const evidenceRef = (
 	evidenceId: string,
@@ -1067,7 +1084,7 @@ const actionEvidenceReferences = (
 				`eval:${evalResult.id}`,
 				"eval",
 				evalResult.id,
-				`#/evals/${encodeURIComponent(evalResult.id)}`,
+				evalRoute(evalResult.id),
 				"evidence.bundle.eval_results",
 				evalResult.passed ? 0.75 : 0.9,
 				`Eval ${evalResult.evaluatorName} ${evalResult.passed ? "passed" : "failed"}${evalResult.score === null ? "" : ` with score ${evalResult.score}`}.`,
@@ -1607,6 +1624,34 @@ const attachAutoSreTriageContext = async (
 				limit: 5,
 			});
 		}
+		// Secondary match: the same recurrence fingerprint (service + route +
+		// error signature) in this project, so a failure that recurs on a
+		// different span id still surfaces the findings and fixes recorded
+		// before. Entity-id matches stay first.
+		if (faultLocus?.faultLocusSpan) {
+			const spanFp = fingerprintInputFromSpan(
+				faultLocus.faultLocusSpan,
+				environment,
+			);
+			const fingerprint = buildFindingFingerprint({
+				...spanFp,
+				normalizedOperation: spanFp.normalizedOperation ?? "",
+				errorSignature: spanFp.errorSignature ?? "",
+			}).fingerprint;
+			const byFingerprint = await searchInvestigationFindings(db, {
+				projectId,
+				environment,
+				fingerprint,
+				limit: 5,
+			});
+			const seen = new Set(priorFindingsList.map((f) => f.id));
+			for (const f of byFingerprint) {
+				if (!seen.has(f.id) && priorFindingsList.length < 5) {
+					priorFindingsList.push(f);
+					seen.add(f.id);
+				}
+			}
+		}
 		// No unfiltered fallback: unrelated findings would read as relevant
 		// prior art. An empty list is the honest answer.
 		const priorFindings = priorFindingsList.map((f) => ({
@@ -1621,7 +1666,7 @@ const attachAutoSreTriageContext = async (
 
 		for (const br of blastRadii) {
 			const changeId = br.change.id;
-			const changeRoute = `#/changes/${encodeURIComponent(changeId)}`;
+			const changeRoute = changeEntityRoute(changeId);
 			bundle.evidenceReferences.push({
 				evidenceId: `change:${changeId}`,
 				entityKind: "change",
@@ -1655,7 +1700,7 @@ const attachAutoSreTriageContext = async (
 		}
 
 		for (const finding of priorFindingsList) {
-			const findingRoute = `#/findings/${encodeURIComponent(finding.id)}`;
+			const findingRoute = findingEntityRoute(finding.id);
 			bundle.evidenceReferences.push({
 				evidenceId: `finding:${finding.id}`,
 				entityKind: "finding",
@@ -1867,7 +1912,11 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 						runtime.logger,
 					);
 				}
-				return c.json(await materializeBundle(db, projectId, bundle));
+				return respondWithContract(
+					c,
+					"POST /internal/evidence/bundle",
+					await materializeBundle(db, projectId, bundle),
+				);
 			}
 
 			if (anchor.entityKind === "incident") {
@@ -1889,7 +1938,7 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					{ kind: incident.symptomAnchorKind, id: incident.symptomAnchorId },
 				);
 
-				const incRoute = `#/incidents/${encodeURIComponent(incident.id)}`;
+				const incRoute = incidentEntityRoute(incident.id);
 				const baseBundle: EvidenceBundle = {
 					schemaVersion: BUNDLE_SCHEMA_VERSION,
 					intent,
@@ -1958,7 +2007,11 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					baseBundle,
 					runtime.logger,
 				);
-				return c.json(await materializeBundle(db, projectId, enriched));
+				return respondWithContract(
+					c,
+					"POST /internal/evidence/bundle",
+					await materializeBundle(db, projectId, enriched),
+				);
 			}
 
 			if (anchor.entityKind === "change") {
@@ -1982,7 +2035,7 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					null,
 				);
 
-				const changeRoute = `#/changes/${encodeURIComponent(change.id)}`;
+				const changeRoute = changeEntityRoute(change.id);
 				const summary =
 					blastRadius?.summary ??
 					`Change ${change.id} (${change.kind} ${change.version ?? ""}) in ${change.environment}: ${change.summary}`;
@@ -2071,7 +2124,11 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					baseBundle,
 					runtime.logger,
 				);
-				return c.json(await materializeBundle(db, projectId, enriched));
+				return respondWithContract(
+					c,
+					"POST /internal/evidence/bundle",
+					await materializeBundle(db, projectId, enriched),
+				);
 			}
 
 			if (anchor.entityKind === "finding") {
@@ -2099,7 +2156,7 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					{ kind: finding.symptomEntityKind, id: finding.symptomEntityId },
 				);
 
-				const findingRoute = `#/findings/${encodeURIComponent(finding.id)}`;
+				const findingRoute = findingEntityRoute(finding.id);
 				const summary = `${finding.title} (${finding.causalProofTier}, verification=${finding.causalVerificationStatus}, recovery=${finding.recoveryStatus}): ${finding.summary}`;
 				const baseBundle: EvidenceBundle = {
 					schemaVersion: BUNDLE_SCHEMA_VERSION,
@@ -2189,7 +2246,11 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					baseBundle,
 					runtime.logger,
 				);
-				return c.json(await materializeBundle(db, projectId, enriched));
+				return respondWithContract(
+					c,
+					"POST /internal/evidence/bundle",
+					await materializeBundle(db, projectId, enriched),
+				);
 			}
 
 			if (anchor.entityKind !== "trace") {
@@ -2236,7 +2297,11 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					runtime.logger,
 				);
 			}
-			return c.json(await materializeBundle(db, projectId, bundle));
+			return respondWithContract(
+				c,
+				"POST /internal/evidence/bundle",
+				await materializeBundle(db, projectId, bundle),
+			);
 		});
 
 		app.get("/internal/evidence/stats", async (c) => {
@@ -2328,7 +2393,7 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 								expanded_at: string;
 							}>(),
 					]);
-				return c.json({
+				return respondWithContract(c, "GET /internal/evidence/stats", {
 					projectId,
 					generatedAt: new Date().toISOString(),
 					byKind: byKind.results.map((row) => ({
@@ -2366,7 +2431,7 @@ export const evidenceRetrievalRoutesPlugin: CollectorPlugin = {
 					})),
 				});
 			} catch {
-				return c.json({
+				return respondWithContract(c, "GET /internal/evidence/stats", {
 					projectId,
 					generatedAt: new Date().toISOString(),
 					byKind: [],