@opengeni/api-router 2.4.2-canary.0 → 2.5.0

package/src/routes/sessions.ts

@@ -66,12 +66,23 @@ import {
   UpdateSessionToolPolicyRequest,
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
+  WORK_CLAIM_CANONICAL_KEY_MAX_BYTES,
+  WORK_CLAIM_DISCOVERY_LIMIT,
+  WORK_CLAIM_NAMESPACE_MAX_BYTES,
+  WORK_DISCOVERY_QUERY_MAX_CHARS,
+  WORK_DISCOVERY_RECENT_HOURS_MAX,
+  WorkClaimSubjectFilter as WorkClaimSubjectFilterSchema,
+  WorkClaimSubjectType,
+  normalizeWorkClaimCanonicalKey,
+  normalizeWorkClaimNamespace,
   workspaceControlUtf8Bytes,
   type AccessGrant,
   type AttachViewerResponse,
   type SandboxBackend,
   type LineageNode,
   type Session,
+  type SessionStatus,
+  type WorkClaimSubjectFilter,
   type SessionGoalRevision,
   type AgentTopologyPageResponse,
   type ErrorCode,
@@ -173,6 +184,7 @@ import {
   type SandboxRetainedProcess,
   type Database,
   type SessionDiscoveryCursor,
+  type SessionDiscoveryOrderBy,
   type SessionDiscoveryAncestor,
 } from "@opengeni/db";
 import {
@@ -280,6 +292,7 @@ import {
 } from "./workspace-capture";
 import { publishSandboxFileArtifact } from "../sandbox-file-artifacts";
 import { ApiHttpError } from "../http/api-error";
+import { observeWorkDiscovery, summarizeWorkDiscoveryRows } from "../work-discovery-observability";
 
 type SessionRouteDeps = ApiRouteDeps & Pick<ViewerServices, "establishSandboxSession">;
 
@@ -700,71 +713,144 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       throw sessionAuthorizationHttpError(error);
     }
     const query = agentTopologyQuery(c.req.query());
-    const page = await listSessionDiscoverySummaries(db, workspaceId, {
-      limit: query.limit,
-      orderBy: "updatedAt",
-      subjectId: grant.subjectId,
-      ...(query.cursor ? { cursor: query.cursor } : {}),
-      ...(query.search ? { search: query.search } : { parentSessionId: query.parentSessionId }),
-      ...(authorizationScope ? { authorizationScope } : {}),
-    });
-    const ancestorPaths = query.search
-      ? await listSessionDiscoveryAncestorPaths(
-          db,
-          workspaceId,
-          page.sessions.map((session) => session.id),
-          authorizationScope ?? undefined,
-        )
-      : new Map<string, SessionDiscoveryAncestor[]>();
-    const sessions: AgentTopologyPageResponse["sessions"] = page.sessions.map((session) => {
-      const blocker = session.effectiveControl.primaryBlocker;
-      return {
-        id: session.id,
-        title: session.title,
-        titleTruncated:
-          session.titleOriginalChars !== null &&
-          session.titleOriginalChars > Array.from(session.title ?? "").length,
-        parentSessionId: session.parentSessionId,
-        rootSessionId: session.rootSessionId,
-        nestedAgentDepth: session.nestedAgentDepth,
-        ancestorPath: (ancestorPaths.get(session.id) ?? []).map((ancestor) => ({
-          id: ancestor.id,
-          title: ancestor.title,
+    const startedAtMs = performance.now();
+    const mode = query.subject ? "subject" : query.query ? "query" : "browse";
+    const metricAuthorizationScope = authorizationScope?.kind === "scoped" ? "scoped" : "workspace";
+    if ((query.query || query.subject) && !settings.workDiscoveryEnabled) {
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: "disabled",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: 0,
+        resultCount: 0,
+        overlapCount: 0,
+        matchCounts: {},
+      });
+      throw new HTTPException(503, {
+        message: "Agent work discovery is disabled by the operator.",
+      });
+    }
+    try {
+      const orderBy: SessionDiscoveryOrderBy =
+        query.query || query.subject ? "relevance" : "updatedAt";
+      const page = await listSessionDiscoverySummaries(db, workspaceId, {
+        limit: query.limit,
+        orderBy,
+        subjectId: grant.subjectId,
+        ...(query.cursor ? { cursor: query.cursor } : {}),
+        ...(query.parentSessionId !== undefined ? { parentSessionId: query.parentSessionId } : {}),
+        ...(query.rootSessionId ? { rootSessionId: query.rootSessionId } : {}),
+        ...(query.query ? { query: query.query } : {}),
+        ...(query.statuses ? { statuses: query.statuses } : {}),
+        activeOnly: query.activeOnly,
+        ...(query.recentHours !== undefined ? { recentHours: query.recentHours } : {}),
+        ...(query.subject ? { subject: query.subject } : {}),
+        ...(query.claimLimit !== undefined ? { claimLimit: query.claimLimit } : {}),
+        includeWorkDiscovery: settings.workDiscoveryEnabled,
+        ...(authorizationScope ? { authorizationScope } : {}),
+      });
+      const ancestorPaths =
+        query.query || query.subject
+          ? await listSessionDiscoveryAncestorPaths(
+              db,
+              workspaceId,
+              page.sessions.map((session) => session.id),
+              authorizationScope ?? undefined,
+              grant.subjectId,
+            )
+          : new Map<string, SessionDiscoveryAncestor[]>();
+      const sessions: AgentTopologyPageResponse["sessions"] = page.sessions.map((session) => {
+        const blocker = session.effectiveControl.primaryBlocker;
+        return {
+          id: session.id,
+          title: session.title,
           titleTruncated:
-            ancestor.titleOriginalChars !== null &&
-            ancestor.titleOriginalChars > Array.from(ancestor.title ?? "").length,
-        })),
-        status: session.status,
-        pause: {
-          state: session.effectiveControl.state,
-          additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
-          source: blocker
+            session.titleOriginalChars !== null &&
+            session.titleOriginalChars > Array.from(session.title ?? "").length,
+          parentSessionId: session.parentSessionId,
+          rootSessionId: session.rootSessionId,
+          nestedAgentDepth: session.nestedAgentDepth,
+          ancestorPath: (ancestorPaths.get(session.id) ?? []).map((ancestor) => ({
+            id: ancestor.id,
+            title: ancestor.title,
+            titleTruncated:
+              ancestor.titleOriginalChars !== null &&
+              ancestor.titleOriginalChars > Array.from(ancestor.title ?? "").length,
+          })),
+          status: session.status,
+          goal: session.goal
             ? {
-                kind: blocker.kind,
-                ...(blocker.sessionId ? { sessionId: blocker.sessionId } : {}),
-                displayName: blocker.displayName,
-                displayNameTruncated:
-                  blocker.displayNameOriginalChars > Array.from(blocker.displayName).length,
+                status: session.goal.status,
+                summary: session.goal.text,
+                summaryTruncated:
+                  session.goal.textOriginalChars > Array.from(session.goal.text).length,
               }
             : null,
-        },
-        children: session.treeStats,
-        createdAt: session.createdAt,
-        updatedAt: session.updatedAt,
-      };
-    });
-    return c.json({
-      sessions,
-      total: page.total,
-      hasMore: page.hasMore,
-      nextCursor: page.nextCursor
-        ? encodeAgentTopologyCursor({
-            cursor: page.nextCursor,
-            parentSessionId: query.parentSessionId,
-            search: query.search ?? null,
-          })
-        : null,
-    } satisfies AgentTopologyPageResponse);
+          pause: {
+            state: session.effectiveControl.state,
+            additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
+            source: blocker
+              ? {
+                  kind: blocker.kind,
+                  ...(blocker.sessionId ? { sessionId: blocker.sessionId } : {}),
+                  displayName: blocker.displayName,
+                  displayNameTruncated:
+                    blocker.displayNameOriginalChars > Array.from(blocker.displayName).length,
+                }
+              : null,
+          },
+          children: session.treeStats,
+          relatedWork: session.workDiscovery,
+          createdAt: session.createdAt,
+          updatedAt: session.updatedAt,
+        };
+      });
+      const response = {
+        sessions,
+        total: page.total,
+        hasMore: page.hasMore,
+        humanAdvisoriesEnabled:
+          settings.workDiscoveryEnabled && settings.workDiscoveryHumanAdvisoriesEnabled,
+        nextCursor: page.nextCursor
+          ? encodeAgentTopologyCursor({
+              cursor: page.nextCursor,
+              parentSessionId: query.parentSessionId === undefined ? "all" : query.parentSessionId,
+              rootSessionId: query.rootSessionId ?? null,
+              query: query.query ?? null,
+              statuses: query.statuses ?? [],
+              activeOnly: query.activeOnly,
+              recentHours: query.recentHours ?? null,
+              subject: query.subject ?? null,
+              claimLimit: query.claimLimit ?? null,
+            })
+          : null,
+      } satisfies AgentTopologyPageResponse;
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: sessions.length === 0 ? "empty" : "ok",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: Buffer.byteLength(JSON.stringify(response), "utf8"),
+        ...summarizeWorkDiscoveryRows(sessions),
+      });
+      return c.json(response);
+    } catch (error) {
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: "error",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: 0,
+        resultCount: 0,
+        overlapCount: 0,
+        matchCounts: {},
+      });
+      throw error;
+    }
   });
 
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
@@ -4509,12 +4595,18 @@ function sessionListQuery(
 
 export type AgentTopologyCursorEnvelope = {
   cursor: SessionDiscoveryCursor;
-  parentSessionId: string | null;
-  search: string | null;
+  parentSessionId: string | null | "all";
+  rootSessionId: string | null;
+  query: string | null;
+  statuses: SessionStatus[];
+  activeOnly: boolean;
+  recentHours: number | null;
+  subject: WorkClaimSubjectFilter | null;
+  claimLimit: number | null;
 };
 
 export function encodeAgentTopologyCursor(value: AgentTopologyCursorEnvelope): string {
-  return Buffer.from(JSON.stringify({ v: 1, ...value }), "utf8").toString("base64url");
+  return Buffer.from(JSON.stringify({ v: 2, ...value }), "utf8").toString("base64url");
 }
 
 function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
@@ -4524,25 +4616,92 @@ function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
     });
   }
   try {
-    const parsed = z
+    const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as unknown;
+    const legacy = z
       .object({
         v: z.literal(1),
         parentSessionId: z.string().uuid().nullable(),
-        search: z.string().max(200).nullable(),
+        search: z.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS).nullable(),
+        cursor: z.object({
+          orderBy: z.literal("updatedAt"),
+          sortRevision: z.string().max(64),
+          sortAt: z.string().max(64),
+          id: z.string().uuid(),
+          snapshotAt: z.string().max(64),
+          snapshotRevision: z.string().max(64),
+          updatedAfter: z.null(),
+        }),
+      })
+      .safeParse(decoded);
+    if (legacy.success) {
+      if (legacy.data.search !== null) {
+        throw new Error("legacy search cursor is not relevance-fenced");
+      }
+      const cursor = {
+        ...legacy.data.cursor,
+        sortRank: null,
+        filterHash: null,
+      } satisfies SessionDiscoveryCursor;
+      return {
+        cursor,
+        parentSessionId: legacy.data.parentSessionId,
+        rootSessionId: null,
+        query: null,
+        statuses: [],
+        activeOnly: false,
+        recentHours: null,
+        subject: null,
+        claimLimit: null,
+      };
+    }
+    const parsed = z
+      .object({
+        v: z.literal(2),
+        parentSessionId: z.union([z.string().uuid(), z.literal("all"), z.null()]),
+        rootSessionId: z.string().uuid().nullable(),
+        query: z.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS).nullable(),
+        statuses: z
+          .array(
+            z.enum([
+              "queued",
+              "running",
+              "idle",
+              "requires_action",
+              "recovering",
+              "waiting_capacity",
+              "failed",
+              "cancelled",
+            ]),
+          )
+          .max(8),
+        activeOnly: z.boolean(),
+        recentHours: z.number().int().positive().max(WORK_DISCOVERY_RECENT_HOURS_MAX).nullable(),
+        subject: z
+          .object({
+            namespace: z.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES),
+            type: WorkClaimSubjectType,
+            canonicalKey: z.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES),
+          })
+          .strict()
+          .nullable(),
+        claimLimit: z.number().int().positive().max(WORK_CLAIM_DISCOVERY_LIMIT).nullable(),
         cursor: z.object({
-          orderBy: z.enum(["createdAt", "updatedAt"]),
+          orderBy: z.enum(["updatedAt", "relevance"]),
+          sortRank: z.number().int().nonnegative().nullable(),
           sortRevision: z.string().max(64),
           sortAt: z.string().max(64),
           id: z.string().uuid(),
           snapshotAt: z.string().max(64),
           snapshotRevision: z.string().max(64),
-          updatedAfter: z.string().max(64).nullable(),
+          updatedAfter: z.null(),
+          filterHash: z
+            .string()
+            .regex(/^[0-9a-f]{64}$/)
+            .nullable(),
         }),
       })
-      .parse(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+      .parse(decoded);
     if (
-      parsed.cursor.orderBy !== "updatedAt" ||
-      parsed.cursor.updatedAfter !== null ||
       !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.sortRevision) ||
       !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.snapshotRevision) ||
       BigInt(parsed.cursor.sortRevision) > 9_223_372_036_854_775_807n ||
@@ -4552,6 +4711,14 @@ function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
     ) {
       throw new Error("invalid topology cursor fields");
     }
+    if (
+      (parsed.cursor.orderBy === "relevance" &&
+        (parsed.cursor.sortRank === null || parsed.cursor.filterHash === null)) ||
+      (parsed.cursor.orderBy === "updatedAt" &&
+        (parsed.cursor.sortRank !== null || parsed.cursor.filterHash !== null))
+    ) {
+      throw new Error("invalid topology cursor relevance fields");
+    }
     return parsed;
   } catch {
     throw new HTTPException(400, {
@@ -4562,8 +4729,14 @@ function decodeAgentTopologyCursor(value: string): AgentTopologyCursorEnvelope {
 
 export function agentTopologyQuery(query: Record<string, string>): {
   limit: number;
-  parentSessionId: string | null;
-  search: string | undefined;
+  parentSessionId: string | null | undefined;
+  rootSessionId: string | undefined;
+  query: string | undefined;
+  statuses: SessionStatus[] | undefined;
+  activeOnly: boolean;
+  recentHours: number | undefined;
+  subject: WorkClaimSubjectFilter | undefined;
+  claimLimit: number | undefined;
   cursor: SessionDiscoveryCursor | undefined;
 } {
   const rawLimit = query.limit;
@@ -4583,22 +4756,139 @@ export function agentTopologyQuery(query: Record<string, string>): {
       message: 'parentSessionId must be a session id or the literal "null"',
     });
   }
-  const parentSessionId = rawParent === undefined || rawParent === "null" ? null : rawParent;
-  const search = query.search?.trim();
-  if (search && search.length > 200) {
+  const rootSessionId = query.rootSessionId?.trim();
+  if (rootSessionId && !z.string().uuid().safeParse(rootSessionId).success) {
+    throw new HTTPException(400, { message: "rootSessionId must be a session id" });
+  }
+  const normalizeSearchQuery = (value: string | undefined): string | undefined => {
+    if (value === undefined) return undefined;
+    const canonical = value.normalize("NFKC");
+    if (/[\u0000-\u001f\u007f-\u009f]/u.test(canonical)) {
+      throw new HTTPException(400, { message: "query must not contain control characters" });
+    }
+    const normalized = canonical.trim().replace(/\s+/gu, " ").toLowerCase();
+    if (!normalized) return undefined;
+    if (Array.from(normalized).length > WORK_DISCOVERY_QUERY_MAX_CHARS) {
+      throw new HTTPException(400, {
+        message: `query must be at most ${WORK_DISCOVERY_QUERY_MAX_CHARS} characters`,
+      });
+    }
+    return normalized;
+  };
+  const requestedQuery = normalizeSearchQuery(query.query);
+  const legacySearch = normalizeSearchQuery(query.search);
+  const searchQuery = requestedQuery ?? legacySearch;
+  if (requestedQuery && legacySearch && requestedQuery !== legacySearch) {
+    throw new HTTPException(400, { message: "query and legacy search must match" });
+  }
+  const statuses = query.statuses
+    ? [
+        ...new Set(
+          query.statuses
+            .split(",")
+            .map((status) => status.trim())
+            .filter(Boolean),
+        ),
+      ].sort()
+    : [];
+  const parsedStatuses = z
+    .array(
+      z.enum([
+        "queued",
+        "running",
+        "idle",
+        "requires_action",
+        "recovering",
+        "waiting_capacity",
+        "failed",
+        "cancelled",
+      ]),
+    )
+    .max(8)
+    .safeParse(statuses);
+  if (!parsedStatuses.success) {
+    throw new HTTPException(400, { message: "statuses contains an unsupported lifecycle state" });
+  }
+  const activeOnly = query.activeOnly === "true";
+  if (
+    query.activeOnly !== undefined &&
+    query.activeOnly !== "true" &&
+    query.activeOnly !== "false"
+  ) {
+    throw new HTTPException(400, { message: "activeOnly must be true or false" });
+  }
+  const recentHours = query.recentHours === undefined ? undefined : Number(query.recentHours);
+  if (
+    recentHours !== undefined &&
+    (!Number.isSafeInteger(recentHours) ||
+      recentHours < 1 ||
+      recentHours > WORK_DISCOVERY_RECENT_HOURS_MAX)
+  ) {
     throw new HTTPException(400, {
-      message: "search must be at most 200 characters",
+      message: `recentHours must be an integer between 1 and ${WORK_DISCOVERY_RECENT_HOURS_MAX}`,
+    });
+  }
+  const subjectFields = [query.subjectNamespace, query.subjectType, query.subjectKey];
+  if (subjectFields.some((value) => value !== undefined) && subjectFields.some((value) => !value)) {
+    throw new HTTPException(400, {
+      message: "subjectNamespace, subjectType, and subjectKey must be supplied together",
     });
   }
-  if (search && rawParent !== undefined) {
+  const parsedSubject = subjectFields.every((value) => value !== undefined)
+    ? WorkClaimSubjectFilterSchema.safeParse({
+        namespace: normalizeWorkClaimNamespace(query.subjectNamespace!),
+        type: query.subjectType,
+        canonicalKey: normalizeWorkClaimCanonicalKey(query.subjectKey!),
+      })
+    : null;
+  if (parsedSubject && !parsedSubject.success) {
+    throw new HTTPException(400, { message: "exact subject filter is invalid" });
+  }
+  const subject = parsedSubject?.success ? parsedSubject.data : undefined;
+  if (searchQuery && subject) {
+    throw new HTTPException(400, { message: "query cannot be combined with an exact subject" });
+  }
+  const relevanceRequested = Boolean(searchQuery || subject);
+  const parentSessionId =
+    rawParent === undefined
+      ? relevanceRequested
+        ? undefined
+        : null
+      : rawParent === "null"
+        ? null
+        : rawParent;
+  const claimLimit = query.claimLimit === undefined ? undefined : Number(query.claimLimit);
+  if (
+    claimLimit !== undefined &&
+    (!Number.isSafeInteger(claimLimit) || claimLimit < 1 || claimLimit > WORK_CLAIM_DISCOVERY_LIMIT)
+  ) {
     throw new HTTPException(400, {
-      message: "search cannot be combined with parentSessionId",
+      message: `claimLimit must be an integer between 1 and ${WORK_CLAIM_DISCOVERY_LIMIT}`,
     });
   }
   const envelope = query.cursor ? decodeAgentTopologyCursor(query.cursor) : undefined;
+  const expectedEnvelope = {
+    parentSessionId: parentSessionId === undefined ? "all" : parentSessionId,
+    rootSessionId: rootSessionId ?? null,
+    query: searchQuery || null,
+    statuses: parsedStatuses.data,
+    activeOnly,
+    recentHours: recentHours ?? null,
+    subject: subject ?? null,
+    claimLimit: claimLimit ?? null,
+  };
   if (
     envelope &&
-    (envelope.parentSessionId !== parentSessionId || envelope.search !== (search || null))
+    JSON.stringify({
+      parentSessionId: envelope.parentSessionId,
+      rootSessionId: envelope.rootSessionId,
+      query: envelope.query,
+      statuses: envelope.statuses,
+      activeOnly: envelope.activeOnly,
+      recentHours: envelope.recentHours,
+      subject: envelope.subject,
+      claimLimit: envelope.claimLimit,
+    }) !== JSON.stringify(expectedEnvelope)
   ) {
     throw new HTTPException(400, {
       message: "agent topology cursor does not match its filters",
@@ -4607,7 +4897,13 @@ export function agentTopologyQuery(query: Record<string, string>): {
   return {
     limit,
     parentSessionId,
-    search: search || undefined,
+    rootSessionId: rootSessionId || undefined,
+    query: searchQuery || undefined,
+    statuses: parsedStatuses.data.length > 0 ? parsedStatuses.data : undefined,
+    activeOnly,
+    recentHours,
+    subject,
+    claimLimit,
     cursor: envelope?.cursor,
   };
 }

package/src/work-discovery-observability.ts

@@ -0,0 +1,121 @@
+import type { WorkDiscoveryMatchClass } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+
+export type WorkDiscoverySurface = "first_party_mcp" | "agent_topology";
+export type WorkDiscoveryMode = "browse" | "query" | "subject";
+export type WorkDiscoveryOutcome = "ok" | "empty" | "disabled" | "error";
+export type WorkDiscoveryAuthorizationScope = "workspace" | "scoped";
+
+export type WorkDiscoveryObservation = {
+  surface: WorkDiscoverySurface;
+  mode: WorkDiscoveryMode;
+  outcome: WorkDiscoveryOutcome;
+  authorizationScope: WorkDiscoveryAuthorizationScope;
+  durationMs: number;
+  responseBytes: number;
+  resultCount: number;
+  overlapCount: number;
+  matchCounts: Partial<Record<WorkDiscoveryMatchClass, number>>;
+};
+
+type WorkDiscoveryObservedRow = {
+  relatedWork: {
+    match: { class: WorkDiscoveryMatchClass } | null;
+    possibleOverlap: boolean;
+  };
+};
+
+const RESULT_BUCKETS = [0, 1, 2, 4, 8, 16, 32, 64, 100];
+const RESPONSE_BYTE_BUCKETS = [512, 1_024, 4_096, 16_384, 65_536, 128_000, 262_144];
+const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5];
+
+export function summarizeWorkDiscoveryRows(
+  rows: readonly WorkDiscoveryObservedRow[],
+): Pick<WorkDiscoveryObservation, "resultCount" | "overlapCount" | "matchCounts"> {
+  const matchCounts: WorkDiscoveryObservation["matchCounts"] = {};
+  let overlapCount = 0;
+  for (const row of rows) {
+    if (row.relatedWork.possibleOverlap) overlapCount += 1;
+    const matchClass = row.relatedWork.match?.class;
+    if (matchClass) matchCounts[matchClass] = (matchCounts[matchClass] ?? 0) + 1;
+  }
+  return { resultCount: rows.length, overlapCount, matchCounts };
+}
+
+/**
+ * Low-cardinality work-discovery telemetry. Identifiers, search text, subject
+ * keys, titles, goals, claim labels, versions, and provenance are excluded by
+ * construction. An observability failure never changes product behavior.
+ */
+export function observeWorkDiscovery(
+  observability: Observability | null | undefined,
+  observation: WorkDiscoveryObservation,
+): void {
+  if (!observability) return;
+  const labels = {
+    surface: observation.surface,
+    mode: observation.mode,
+    outcome: observation.outcome,
+    authorization_scope: observation.authorizationScope,
+  };
+  try {
+    observability.incrementCounter({
+      name: "opengeni_work_discovery_requests_total",
+      help: "Advisory work-discovery requests by bounded surface, mode, outcome, and authorization scope.",
+      labels,
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_duration_seconds",
+      help: "Advisory work-discovery request duration in seconds.",
+      labels,
+      buckets: DURATION_BUCKETS,
+      value: Math.max(0, observation.durationMs) / 1_000,
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_results",
+      help: "Bounded advisory work-discovery result rows per request.",
+      labels: { surface: observation.surface, mode: observation.mode },
+      buckets: RESULT_BUCKETS,
+      value: Math.max(0, Math.floor(observation.resultCount)),
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_response_bytes",
+      help: "Serialized advisory work-discovery response bytes.",
+      labels: { surface: observation.surface, mode: observation.mode },
+      buckets: RESPONSE_BYTE_BUCKETS,
+      value: Math.max(0, Math.floor(observation.responseBytes)),
+    });
+    if (observation.overlapCount > 0) {
+      observability.incrementCounter({
+        name: "opengeni_work_discovery_overlap_results_total",
+        help: "Advisory discovery rows carrying a possible-overlap explanation.",
+        labels: { surface: observation.surface, mode: observation.mode },
+        amount: Math.floor(observation.overlapCount),
+      });
+    }
+    for (const matchClass of ["exact_subject", "title", "goal", "fuzzy"] as const) {
+      const amount = Math.floor(observation.matchCounts[matchClass] ?? 0);
+      if (amount < 1) continue;
+      observability.incrementCounter({
+        name: "opengeni_work_discovery_matches_total",
+        help: "Advisory discovery matches by stable explanation class.",
+        labels: {
+          surface: observation.surface,
+          mode: observation.mode,
+          match_class: matchClass,
+        },
+        amount,
+      });
+    }
+  } catch {
+    try {
+      observability.incrementCounter({
+        name: "opengeni_observability_observer_errors_total",
+        help: "Observability observer failures isolated from product execution.",
+        labels: { observer: "work_discovery" },
+      });
+    } catch {
+      // The metrics registry itself is unhealthy. Discovery remains authoritative.
+    }
+  }
+}