@saptools/service-flow 0.1.52 → 0.1.54

package/src/trace/trace-engine.ts

@@ -1,8 +1,6 @@
 import type { Db } from '../db/connection.js';
 import { reposByName } from '../db/repositories.js';
 import { extractPlaceholders } from '../linker/dynamic-edge-resolver.js';
-import { normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
-import { resolveOperation } from '../linker/service-resolver.js';
 import type { ImplementationHint, TraceEdge, TraceOptions, TraceResult, TraceStart } from '../types.js';
 import { baseTraceEvidence, edgeTarget, runtimeNoCandidateDiagnostics, runtimeResolution, runtimeVariableDiagnostic, type TraceGraphRow } from './evidence.js';
 import { dynamicCandidateBranches } from './dynamic-branches.js';
@@ -10,7 +8,22 @@ import {
   loadTraceDiagnostics,
   prependTraceDiagnostic,
 } from './002-trace-diagnostics.js';
-import { implementationHintDiagnostic, selectImplementation, type ImplementationSelection } from './implementation-hints.js';
+import { implementationHintDiagnostic } from './implementation-hints.js';
+import {
+  contextualImplementationSelection,
+  hintedImplementationSelection,
+} from './005-implementation-selection.js';
+import { implementationStartDiagnostic } from './007-implementation-start-diagnostic.js';
+import {
+  contextualRuntimeResolution,
+  type ContextBinding,
+} from './008-contextual-runtime-state.js';
+import {
+  handlerMethodNode,
+  withSelectedHandlerProvenance,
+  type SelectedHandlerEvidence,
+} from './009-selected-handler-provenance.js';
+import { boundCandidateLikeEvidence } from '../utils/000-bounded-projection.js';
 import {
   ambiguousStartDiagnostic,
   selectorNotFoundDiagnostic,
@@ -53,32 +66,6 @@ interface GraphRow extends Record<string, unknown> {
   unresolved_reason?: string;
   status?: string;
 }
-interface ContextBinding {
-  bindingId?: number;
-  alias?: string;
-  aliasExpr?: string;
-  destinationExpr?: string;
-  servicePathExpr?: string;
-  requireServicePath?: string;
-  requireDestination?: string;
-  effectiveServicePath?: string;
-  effectiveDestination?: string;
-  sourceFile?: string;
-  sourceLine?: number;
-  source: string;
-  callerArgument?: string;
-  callerProperty?: string;
-  calleeParameter?: string;
-  calleeObjectProperty?: string;
-  calleeLocalDestructuredIdentifier?: string;
-  parameterPropertyAliasKind?: unknown;
-  parameterPropertyAliasLine?: unknown;
-  calleeReceiver: string;
-  callerSite?: { sourceFile?: string; sourceLine?: number };
-  calleeSite?: { sourceFile?: string; sourceLine?: number };
-  resolutionStatus?: 'selected' | 'ambiguous';
-  bindingCandidates?: Array<Record<string, unknown>>;
-}
 interface ImplementationHintOptions {
   implementationRepo?: string;
   implementationHints?: ImplementationHint[];
@@ -110,31 +97,21 @@ function operationStartScope(db: Db, repoId: number | undefined, start: TraceSta
   const operationId = String(rows[0]?.operationId);
   const impl = implementationScope(db, operationId);
   if (impl.edge?.status === 'resolved' && impl.files.size > 0) return { files: impl.files, symbols: impl.symbolId ? new Set([impl.symbolId]) : undefined, repoId: impl.repoId, operationId, diagnostics: [] };
-  const hinted = implementationMethodIdFromHint(impl.edge, hintOptions);
+  const hinted = hintedImplementationSelection(
+    db, impl.edge, operationId, hintOptions,
+  );
   if (hinted.methodId) {
     const hintedScope = handlerScope(db, hinted.methodId);
     if (hintedScope?.files.size) return { files: hintedScope.files, symbols: hintedScope.symbolId ? new Set([hintedScope.symbolId]) : undefined, repoId: hintedScope.repoId, operationId, diagnostics: [] };
   }
   if (impl.edge) {
     const evidence = parseEvidence(impl.edge.evidence_json);
-    const hintDiagnostic = implementationHintDiagnostic(hinted, evidence.implementationHintSuggestions);
-    const diagnostics = [{ severity: 'warning', code: impl.edge.status === 'ambiguous' ? 'trace_start_ambiguous' : 'trace_start_implementation_unresolved', message: `Indexed operation matched but implementation edge is ${String(impl.edge.status ?? 'unresolved')}`, resolutionStage: 'implementation', resolutionStatus: impl.edge.status === 'ambiguous' ? 'ambiguous_implementation' : 'rejected_implementation', implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, implementationAmbiguityReasons: evidence.ambiguityReasons, implementationRejectionReasons: implementationRejectionReasons(evidence), implementationHintSuggestions: evidence.implementationHintSuggestions, candidates: evidence.candidates }];
+    const hintDiagnostic = implementationHintDiagnostic(hinted, evidence);
+    const diagnostics = [implementationStartDiagnostic(impl.edge, evidence)];
     return { operationId, diagnostics: hintDiagnostic ? [hintDiagnostic, ...diagnostics] : diagnostics };
   }
   return { operationId, diagnostics: [{ severity: 'warning', code: 'trace_start_implementation_unresolved', message: 'Indexed operation matched but no implementation candidate exists', resolutionStage: 'implementation', resolutionStatus: 'operation_without_implementation' }] };
 }
-function implementationRejectionReasons(evidence: Record<string, unknown>): string[] {
-  const candidates = Array.isArray(evidence.candidates)
-    ? evidence.candidates.filter((item): item is Record<string, unknown> =>
-        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
-    : [];
-  const reasons = candidates.flatMap((candidate) =>
-    Array.isArray(candidate.rejectedReasons)
-      ? candidate.rejectedReasons.filter((reason): reason is string =>
-          typeof reason === 'string')
-      : []);
-  return [...new Set(reasons)].sort();
-}
 function sourceFilesForStart(
   db: Db,
   repoId: number | undefined,
@@ -222,11 +199,6 @@ function handlerFilesForOperation(db: Db, operationId: string): Set<string> {
 function implementationEdge(db: Db, operationId: string): GraphRow | undefined {
   return db.prepare("SELECT * FROM graph_edges WHERE edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND from_kind='operation' AND from_id=? ORDER BY CASE status WHEN 'resolved' THEN 0 WHEN 'ambiguous' THEN 1 ELSE 2 END,id LIMIT 1").get(operationId) as GraphRow | undefined;
 }
-function handlerMethodNode(db: Db, methodId: string): Record<string, unknown> | undefined {
-  const row = db.prepare(`SELECT hm.id methodId,hm.method_name methodName,hm.decorator_value decoratorValue,hm.source_line sourceLine,hc.class_name className,hc.source_file sourceFile,r.name repoName,r.id repoId FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id JOIN repositories r ON r.id=hc.repo_id WHERE hm.id=?`).get(methodId) as Record<string, unknown> | undefined;
-  if (!row) return undefined;
-  return { id: `handler_method:${methodId}`, kind: 'handler_method', label: `${String(row.repoName)}:${String(row.className)}.${String(row.methodName)}`, ...row };
-}
 function implementationScope(db: Db, operationId: string): { repoId?: number; files: Set<string>; symbolId?: number; edge?: GraphRow } {
   const edge = implementationEdge(db, operationId);
   if (!edge || edge.status !== 'resolved') return { files: new Set(), edge };
@@ -235,29 +207,6 @@ function implementationScope(db: Db, operationId: string): { repoId?: number; fi
     return { repoId: row?.repoId, files: new Set(), edge };
   return { repoId: row?.repoId, files: new Set(row?.sourceFile ? [row.sourceFile] : []), symbolId: row?.symbolId, edge };
 }
-function implementationMethodIdFromHint(edge: GraphRow | undefined, options: ImplementationHintOptions): ImplementationSelection {
-  if (!edge || edge.status !== 'ambiguous') return { blocksAutomatic: false, evidence: { status: 'not_applicable' } };
-  return selectImplementation(parseEvidence(edge.evidence_json), options.implementationHints, options.implementationRepo);
-}
-function contextImplementationMethodId(edge: GraphRow | undefined, callerRepoId: number | undefined, remoteEvidence: Record<string, unknown>, hintOptions: ImplementationHintOptions): ImplementationSelection {
-  const hinted = implementationMethodIdFromHint(edge, hintOptions);
-  if (hinted.methodId) return hinted;
-  if (hinted.blocksAutomatic) return hinted;
-  if (!edge || edge.status !== 'ambiguous' || callerRepoId === undefined) return hinted;
-  const evidence = JSON.parse(String(edge.evidence_json || '{}')) as { candidates?: Array<{ accepted?: boolean; methodId?: number; handlerPackage?: { id?: number; name?: string }; applicationPackage?: { id?: number; name?: string }; reasons?: string[]; score?: number }> };
-  const scores = (evidence.candidates ?? []).filter((item) => item.accepted).map((item) => {
-    const reasons: string[] = [];
-    let score = Number(item.score ?? 0);
-    if (Number(item.handlerPackage?.id) === callerRepoId) { score += 10; reasons.push('handler_package_matches_caller_repository'); }
-    if (Number(item.applicationPackage?.id) === callerRepoId) { score += 10; reasons.push('registration_package_matches_caller_repository'); }
-    if (typeof remoteEvidence.effectiveServicePath === 'string' || typeof remoteEvidence.effectiveDestination === 'string' || typeof remoteEvidence.effectiveAlias === 'string') { score += 1; reasons.push('remote_call_context_available'); }
-    return { methodId: item.methodId, score, reasons, handlerPackage: item.handlerPackage, applicationPackage: item.applicationPackage };
-  }).sort((a, b) => b.score - a.score);
-  if (scores.length === 0) return { blocksAutomatic: false, evidence: { status: 'not_applicable', candidateScores: [] } };
-  const [first, second] = scores;
-  if (first && first.methodId !== undefined && first.score > 0 && (!second || first.score > second.score)) return { methodId: String(first.methodId), blocksAutomatic: false, evidence: { status: 'selected', selectedMethodId: first.methodId, candidateScores: scores } };
-  return { blocksAutomatic: false, evidence: hinted.evidence.reason === 'no_scoped_hint_matched_edge' ? hinted.evidence : { status: 'tied', tieReason: scores.length > 1 ? 'duplicate_helper_implementation_candidates' : 'no_unique_materially_stronger_candidate', candidateScores: scores } };
-}
 function handlerScope(db: Db, methodId: string): { repoId?: number; files: Set<string>; symbolId?: number } | undefined {
   const row = db.prepare("SELECT hc.repo_id repoId,hc.source_file sourceFile,s.id symbolId FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id LEFT JOIN symbols s ON s.repo_id=hc.repo_id AND s.source_file=hc.source_file AND s.qualified_name=hc.class_name || '.' || hm.method_name AND s.start_line=hm.source_line WHERE hm.id=?").get(methodId) as { repoId?: number; sourceFile?: string; symbolId?: number } | undefined;
   if (!row || typeof row.symbolId !== 'number') return undefined;
@@ -317,11 +266,15 @@ function workspaceIdForCall(db: Db, callId: string): number | undefined {
 function parseEvidence(value: unknown): Record<string, unknown> {
   try {
     const parsed = JSON.parse(String(value || '{}')) as unknown;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+    return isEvidenceRecord(parsed) ? boundCandidateLikeEvidence(parsed) : {};
   } catch {
     return {};
   }
 }
+
+function isEvidenceRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
 function receiverFromEvidence(value: unknown): string | undefined {
   const evidence = parseEvidence(value);
   return typeof evidence.receiver === 'string' ? evidence.receiver : undefined;
@@ -458,35 +411,6 @@ function contextForSymbolCall(db: Db, symbolCall: Record<string, unknown>, calle
   });
   return next;
 }
-function contextualRuntimeResolution(db: Db, call: CallRow, binding: ContextBinding | undefined, workspaceId: number | undefined, persistedRows: GraphRow[] = []): { row?: GraphRow; evidence?: Record<string, unknown>; unresolvedReason?: string } {
-  if (!binding || String(call.call_type) !== 'remote_action' || call.operation_path_expr === undefined || call.operation_path_expr === null) return {};
-  if (binding.resolutionStatus === 'ambiguous') {
-    return {
-      evidence: {
-        contextualServiceBindingAttempted: true,
-        contextualBinding: {
-          source: binding.source,
-          status: 'tied',
-          candidates: binding.bindingCandidates,
-        },
-        contextualResolutionStatus: 'ambiguous',
-        contextualCandidateCount: binding.bindingCandidates?.length ?? 0,
-      },
-      unresolvedReason: 'Ambiguous contextual service binding candidates',
-    };
-  }
-  const normalized = normalizeODataOperationInvocationPath(String(call.operation_path_expr));
-  const op = normalized?.normalizedOperationPath ?? (String(call.operation_path_expr).startsWith('/') ? String(call.operation_path_expr) : `/${String(call.operation_path_expr)}`);
-  const servicePath = binding.effectiveServicePath ?? binding.servicePathExpr ?? binding.requireServicePath;
-  const destination = binding.effectiveDestination ?? binding.destinationExpr ?? binding.requireDestination;
-  const resolution = resolveOperation(db, { servicePath, operationPath: op, alias: binding.aliasExpr ?? binding.alias, destination, hasExplicitOverride: true, isDynamic: false }, workspaceId);
-  const evidence: Record<string, unknown> = { contextualServiceBindingAttempted: true, contextualBinding: { source: binding.source, callerArgument: binding.callerArgument, callerProperty: binding.callerProperty, calleeParameter: binding.calleeParameter, calleeReceiver: binding.calleeReceiver, callerSite: binding.callerSite, calleeSite: binding.calleeSite, bindingSourceFile: binding.sourceFile, bindingSourceLine: binding.sourceLine, alias: binding.alias, aliasExpr: binding.aliasExpr, requireServicePath: binding.requireServicePath, requireDestination: binding.requireDestination, effectiveServicePath: binding.effectiveServicePath, effectiveDestination: binding.effectiveDestination }, operationPath: op, rawOperationPath: normalized?.rawOperationPath, normalizedOperationPath: normalized?.wasInvocation ? normalized.normalizedOperationPath : undefined, invocationArgumentPlaceholderKeys: normalized?.invocationArgumentPlaceholderKeys.length ? normalized.invocationArgumentPlaceholderKeys : undefined, servicePath, serviceAlias: binding.alias, serviceAliasExpr: binding.aliasExpr, destination, requireServicePath: binding.requireServicePath, requireDestination: binding.requireDestination, effectiveServicePath: binding.effectiveServicePath, effectiveDestination: binding.effectiveDestination, contextualResolutionStatus: resolution.status, contextualCandidateCount: resolution.candidates.length, candidates: resolution.candidates, contextualResolutionReasons: resolution.reasons, resolutionReasons: resolution.reasons };
-  if (!resolution.target) return { evidence, unresolvedReason: resolution.status === 'ambiguous' ? 'Ambiguous contextual operation candidates' : resolution.status === 'dynamic' ? `Dynamic contextual target is missing runtime variables: ${resolution.reasons.join(', ')}` : 'No contextual operation candidate matched' };
-  const resolvedEvidence = { ...evidence, contextualServiceBindingSelected: true, targetRepo: resolution.target.repoName, targetServicePath: resolution.target.servicePath, targetOperationPath: resolution.target.operationPath, targetOperation: resolution.target.operationName };
-  const persistedResolved = persistedRows.find((item) => item.status === 'resolved');
-  if (persistedResolved) return { row: undefined, evidence: { ...resolvedEvidence, contextualPreservedPersistedResolvedEdge: true }, unresolvedReason: undefined };
-  return { row: { id: -Number(call.id), edge_type: 'REMOTE_CALL_RESOLVES_TO_OPERATION', from_id: String(call.id), to_kind: 'operation', to_id: String(resolution.target.operationId), confidence: resolution.target.score, evidence_json: JSON.stringify(resolvedEvidence), status: 'resolved' }, evidence: resolvedEvidence, unresolvedReason: undefined };
-}
 export function trace(
   db: Db,
   start: TraceStart,
@@ -524,14 +448,32 @@ export function trace(
     const op = operationNode(db, scope.startOperationId);
     const impl = implementationScope(db, scope.startOperationId);
     if (op) nodes.set(String(op.id), op);
-    const startSelection = implementationMethodIdFromHint(impl.edge, hintOptions);
+    const startSelection = hintedImplementationSelection(
+      db, impl.edge, scope.startOperationId, hintOptions,
+    );
     if (impl.edge && (impl.edge.status === 'resolved' || startSelection.methodId)) {
       const selectedMethodId = impl.edge.status === 'resolved' ? impl.edge.to_id : startSelection.methodId;
-      const implEvidence = { ...parseEvidence(impl.edge.evidence_json), startResolution: { strategy: 'indexed_operation_graph', matchedOperationId: scope.startOperationId, implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, selectedHandlerMethodId: selectedMethodId }, implementationSelection: startSelection.methodId ? startSelection.evidence : undefined };
-      const handlerNode = selectedMethodId ? handlerMethodNode(db, selectedMethodId) : undefined;
-      if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
+      const implEvidence = {
+        ...parseEvidence(impl.edge.evidence_json),
+        startResolution: {
+          strategy: 'indexed_operation_graph',
+          matchedOperationId: scope.startOperationId,
+          implementationEdgeId: impl.edge.id,
+          implementationStatus: impl.edge.status,
+          selectedHandlerMethodId: selectedMethodId,
+        },
+        implementationSelection: startSelection.methodId
+          ? startSelection.evidence : undefined,
+      };
+      const selected: SelectedHandlerEvidence = selectedMethodId
+        ? withSelectedHandlerProvenance(
+          implEvidence, selectedMethodId, handlerMethodNode(db, selectedMethodId),
+        )
+        : { evidence: implEvidence };
+      if (selected.diagnostic) prependTraceDiagnostic(diagnostics, selected.diagnostic);
+      if (selected.handler) nodes.set(String(selected.handler.id), selected.handler);
       seenEdges.add(Number(impl.edge.id));
-      edges.push({ step: 1, type: 'operation_implemented_by_handler', from: op?.label ? String(op.label) : `operation:${scope.startOperationId}`, to: handlerNode?.label ? String(handlerNode.label) : `${impl.edge.to_kind}:${impl.edge.to_id}`, evidence: implEvidence, confidence: Number(impl.edge.confidence ?? 0), unresolvedReason: impl.edge.status === 'resolved' || startSelection.methodId ? undefined : String(impl.edge.unresolved_reason ?? impl.edge.status) });
+      edges.push({ step: 1, type: 'operation_implemented_by_handler', from: op?.label ? String(op.label) : `operation:${scope.startOperationId}`, to: selected.handler?.label ? String(selected.handler.label) : `${impl.edge.to_kind}:${impl.edge.to_id}`, evidence: selected.evidence, confidence: Number(impl.edge.confidence ?? 0), unresolvedReason: selected.unresolvedReason ?? (impl.edge.status === 'resolved' || startSelection.methodId ? undefined : String(impl.edge.unresolved_reason ?? impl.edge.status)) });
     }
   }
   const seenScopes = new Set<string>();
@@ -564,7 +506,7 @@ export function trace(
         const nextKey = `${nextRepoId}:${[...nextSymbols].join(',')}:${[...nextFiles].join(',')}`;
         const calleeNode = symbolNode(db, Number(symbolCall.callee_symbol_id));
         if (calleeNode) nodes.set(String(calleeNode.id), calleeNode);
-        const evidence = { ...(JSON.parse(String(symbolCall.evidence_json || '{}')) as Record<string, unknown>), sourceFile: symbolCall.source_file, sourceLine: symbolCall.source_line, calleeSymbolId: symbolCall.callee_symbol_id, calleeSymbolName: calleeNode?.symbolName, calleeSymbolFile: calleeNode?.sourceFile, resolutionStatus: symbolCall.status };
+        const evidence = { ...parseEvidence(symbolCall.evidence_json), sourceFile: symbolCall.source_file, sourceLine: symbolCall.source_line, calleeSymbolId: symbolCall.callee_symbol_id, calleeSymbolName: calleeNode?.symbolName, calleeSymbolFile: calleeNode?.sourceFile, resolutionStatus: symbolCall.status };
         edges.push({ step: current.depth, type: 'local_symbol_call', from: String(symbolCall.callee_expression), to: calleeNode?.label ? String(calleeNode.label) : `symbol:${String(symbolCall.callee_symbol_id)}`, evidence, confidence: Number(symbolCall.confidence ?? 0.8), unresolvedReason: String(symbolCall.status) === 'resolved' ? undefined : symbolCall.unresolved_reason ? String(symbolCall.unresolved_reason) : undefined });
         if (seenScopes.has(nextKey)) edges.push({ step: current.depth, type: 'cycle', from: String(symbolCall.callee_expression), to: nextKey, evidence: { cycle: true, symbolCallId: symbolCall.id }, confidence: 1, unresolvedReason: 'Cycle detected; downstream symbol already visited' });
         else queue.push({ repoId: nextRepoId, files: nextFiles, symbolIds: nextSymbols, depth: current.depth + 1, context: contextForSymbolCall(db, symbolCall, callerBindings) });
@@ -590,15 +532,13 @@ export function trace(
       for (const row of graphRows) {
         if (seenEdges.has(Number(row.id))) continue;
         seenEdges.add(Number(row.id));
-        const persistedEvidence = JSON.parse(
-          String(row.evidence_json || '{}'),
-        ) as Record<string, unknown>;
+        const persistedEvidence = parseEvidence(row.evidence_json);
         const rawEvidence = baseTraceEvidence(row as TraceGraphRow, call, persistedEvidence, contextual.evidence);
         const effective = runtimeResolution(db, row as TraceGraphRow, rawEvidence, {
           vars: options.vars,
           dynamicMode: options.dynamicMode ?? 'strict',
           maxDynamicCandidates: options.maxDynamicCandidates,
-        }, workspaceIdForCall(db, String(call.id)), contextual.unresolvedReason);
+        }, workspaceIdForCall(db, String(call.id)), contextual.state);
         const evidence = effective.evidence;
         const effectiveRow = effective.row;
         const targetNode = `${effectiveRow.to_kind}:${effectiveRow.to_id}`;
@@ -618,37 +558,69 @@ export function trace(
           confidence: Number(effectiveRow.confidence ?? call.confidence),
           unresolvedReason: effective.unresolvedReason,
         });
-        if ((options.dynamicMode ?? 'strict') === 'candidates')
+        if ((options.dynamicMode ?? 'strict') === 'candidates'
+          && effectiveRow.status !== 'resolved')
           edges.push(...dynamicCandidateBranches(current.depth, call, evidence));
         if (effectiveRow.to_kind === 'operation') {
           const implementation = implementationScope(db, effectiveRow.to_id);
-          const contextSelection = contextImplementationMethodId(implementation.edge, current.repoId, evidence, hintOptions);
+          const contextSelection = contextualImplementationSelection(
+            db, implementation.edge, effectiveRow.to_id, current.repoId, evidence,
+            hintOptions,
+          );
           const contextMethodId = contextSelection.methodId;
-          const contextNode = contextMethodId ? handlerMethodNode(db, contextMethodId) : undefined;
+          let selectedHandlerAvailable = true;
           if (implementation.edge) {
-            const implEvidence = JSON.parse(String(implementation.edge.evidence_json || '{}')) as Record<string, unknown>;
-            const hintDiagnostic = implementationHintDiagnostic(contextSelection, implEvidence.implementationHintSuggestions);
+            const implEvidence = parseEvidence(implementation.edge.evidence_json);
+            const hintDiagnostic = implementationHintDiagnostic(contextSelection, implEvidence);
             if (hintDiagnostic) prependTraceDiagnostic(diagnostics, hintDiagnostic);
-            const handlerNode = implementation.edge.status === 'resolved' ? handlerMethodNode(db, implementation.edge.to_id) : contextNode;
-            const implTo = handlerNode?.label ? String(handlerNode.label) : `${implementation.edge.to_kind}:${implementation.edge.to_id}`;
-            if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
+            const selectedMethodId = implementation.edge.status === 'resolved'
+              ? implementation.edge.to_id : contextMethodId;
+            const selectionEvidence = contextMethodId
+              ? {
+                ...implEvidence,
+                contextualImplementationSelected:
+                  contextSelection.evidence.strategy !== 'implementation_repo_hint',
+                contextualImplementation: contextSelection.evidence,
+                implementationSelection: contextSelection.evidence,
+              }
+              : {
+                ...implEvidence,
+                contextualImplementation: contextSelection.evidence,
+                implementationSelection: contextSelection.evidence,
+              };
+            const selected: SelectedHandlerEvidence = selectedMethodId
+              ? withSelectedHandlerProvenance(
+                selectionEvidence,
+                selectedMethodId,
+                handlerMethodNode(db, selectedMethodId),
+              )
+              : { evidence: selectionEvidence };
+            selectedHandlerAvailable = !selected.unresolvedReason;
+            if (selected.diagnostic) prependTraceDiagnostic(diagnostics, selected.diagnostic);
+            const implTo = selected.handler?.label
+              ? String(selected.handler.label)
+              : `${implementation.edge.to_kind}:${implementation.edge.to_id}`;
+            if (selected.handler) nodes.set(String(selected.handler.id), selected.handler);
             edges.push({
               step: current.depth,
               type: 'operation_implemented_by_handler',
               from: to,
               to: implTo,
-              evidence: contextMethodId
-                ? { ...implEvidence, contextualImplementationSelected: contextSelection.evidence.strategy !== 'implementation_repo_hint', contextualImplementation: contextSelection.evidence, implementationSelection: contextSelection.evidence }
-                : { ...implEvidence, contextualImplementation: contextSelection.evidence, implementationSelection: contextSelection.evidence },
+              evidence: selected.evidence,
               confidence: Number(implementation.edge.confidence ?? 0),
-              unresolvedReason: implementation.edge.status === 'resolved' || contextMethodId ? undefined : String(implementation.edge.unresolved_reason ?? implementation.edge.status),
+              unresolvedReason: selected.unresolvedReason
+                ?? (implementation.edge.status === 'resolved' || contextMethodId
+                  ? undefined
+                  : String(implementation.edge.unresolved_reason ?? implementation.edge.status)),
             });
           }
           if (current.depth >= maxDepth) continue;
           const contextScope = contextMethodId ? handlerScope(db, contextMethodId) : undefined;
           const files = contextScope?.files ?? (implementation.files.size > 0 ? implementation.files : handlerFilesForOperation(db, effectiveRow.to_id));
           const symbolIds = contextScope?.symbolId ? new Set([contextScope.symbolId]) : implementation.symbolId ? new Set([implementation.symbolId]) : undefined;
-          if ((implementation.edge?.status === 'resolved' || contextScope) && files.size > 0) {
+          if (selectedHandlerAvailable
+            && (implementation.edge?.status === 'resolved' || contextScope)
+            && files.size > 0) {
             const targetRepoId = contextScope?.repoId ?? implementation.repoId ?? (db
               .prepare(
                 'SELECT s.repo_id repoId FROM cds_operations o JOIN cds_services s ON s.id=o.service_id WHERE o.id=?',

package/src/utils/000-bounded-projection.ts

@@ -0,0 +1,166 @@
+export const DEFAULT_EVIDENCE_CANDIDATE_LIMIT = 5;
+
+export interface BoundedProjection<T> {
+  totalCount: number;
+  shownCount: number;
+  omittedCount: number;
+  items: T[];
+}
+
+export function projectBounded<T>(
+  values: readonly T[],
+  compare: (left: T, right: T) => number,
+  limit = DEFAULT_EVIDENCE_CANDIDATE_LIMIT,
+): BoundedProjection<T> {
+  const normalizedLimit = positiveLimit(limit);
+  const sorted = [...values].sort(compare);
+  const items = sorted.slice(0, normalizedLimit);
+  return {
+    totalCount: sorted.length,
+    shownCount: items.length,
+    omittedCount: Math.max(0, sorted.length - items.length),
+    items,
+  };
+}
+
+/**
+ * Evidence producers establish semantic order before calling the generic
+ * recursive bounder. Re-sorting here would make a selected decision appear
+ * to be explained by a different candidate.
+ */
+export function projectBoundedInOrder<T>(
+  values: readonly T[],
+  limit = DEFAULT_EVIDENCE_CANDIDATE_LIMIT,
+): BoundedProjection<T> {
+  const normalizedLimit = positiveLimit(limit);
+  const items = values.slice(0, normalizedLimit);
+  return {
+    totalCount: values.length,
+    shownCount: items.length,
+    omittedCount: Math.max(0, values.length - items.length),
+    items,
+  };
+}
+
+export function positiveLimit(value: number | undefined): number {
+  return Number.isFinite(value) && Number(value) > 0
+    ? Math.floor(Number(value))
+    : DEFAULT_EVIDENCE_CANDIDATE_LIMIT;
+}
+
+const candidateLikeCollections = new Set([
+  'candidates',
+  'candidateScores',
+  'candidateFamilies',
+  'candidateEvidence',
+  'candidatePaths',
+  'candidateRawPaths',
+  'candidateNormalizedOperationPaths',
+  'normalizedCandidateOperations',
+  'candidateLiterals',
+  'bindingCandidates',
+  'bindingAlternatives',
+  'implementationHintSuggestions',
+  'selectableImplementationRepositories',
+  'matchedHints',
+  'candidateSuggestions',
+  'dynamicTargetCandidates',
+  'dynamicTargetCandidateSuggestions',
+  'rejectedCandidates',
+  'suggestedVarSets',
+  'copyableExamples',
+  'selectorSuggestions',
+  'serviceSuggestions',
+  'repositories',
+  'examples',
+  'expandedExamples',
+  'registrations',
+]);
+
+/**
+ * Parser facts are retained in their tables; graph evidence only carries a
+ * deterministic explanation. This prevents nested parser alternatives from
+ * bypassing the graph evidence cap while leaving canonical facts queryable.
+ */
+export function boundCandidateLikeEvidence(
+  evidence: Record<string, unknown>,
+  limit = DEFAULT_EVIDENCE_CANDIDATE_LIMIT,
+): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(evidence)) {
+    if (!Array.isArray(value) || !candidateLikeCollections.has(key)) {
+      output[key] = boundNestedEvidence(value, limit);
+      continue;
+    }
+    const projection = projectBoundedInOrder(value, limit);
+    output[key] = projection.items.map((item) => boundNestedEvidence(item, limit));
+    addCollectionCounts(output, evidence, key, projection);
+  }
+  return output;
+}
+
+function boundNestedEvidence(value: unknown, limit: number): unknown {
+  if (Array.isArray(value)) return value.map((item) => boundNestedEvidence(item, limit));
+  if (!isEvidenceRecord(value)) return value;
+  return boundCandidateLikeEvidence(value, limit);
+}
+
+function isEvidenceRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function addCollectionCounts(
+  output: Record<string, unknown>,
+  input: Record<string, unknown>,
+  key: string,
+  projection: BoundedProjection<unknown>,
+): void {
+  const stem = collectionStem(key);
+  const countName = `${stem}Count`;
+  const shownName = `shown${upperFirst(stem)}Count`;
+  const omittedName = `omitted${upperFirst(stem)}Count`;
+  const total = Math.max(numericValue(input[countName]), projection.totalCount);
+  output[countName] = total;
+  output[shownName] = projection.shownCount;
+  output[omittedName] = Math.max(0, total - projection.shownCount);
+}
+
+function collectionStem(key: string): string {
+  const stems: Record<string, string> = {
+    candidates: 'candidate',
+    candidateScores: 'candidateScore',
+    candidateFamilies: 'candidateFamily',
+    candidateEvidence: 'candidateEvidence',
+    candidatePaths: 'candidatePath',
+    candidateRawPaths: 'candidateRawPath',
+    candidateNormalizedOperationPaths: 'candidateNormalizedOperationPath',
+    normalizedCandidateOperations: 'normalizedCandidateOperation',
+    candidateLiterals: 'candidateLiteral',
+    bindingCandidates: 'bindingCandidate',
+    bindingAlternatives: 'bindingAlternative',
+    implementationHintSuggestions: 'implementationHintSuggestion',
+    selectableImplementationRepositories: 'selectableImplementationRepository',
+    matchedHints: 'matchedHint',
+    candidateSuggestions: 'candidateSuggestion',
+    dynamicTargetCandidates: 'dynamicTargetCandidate',
+    dynamicTargetCandidateSuggestions: 'dynamicTargetCandidateSuggestion',
+    rejectedCandidates: 'rejectedCandidate',
+    suggestedVarSets: 'suggestedVarSet',
+    copyableExamples: 'copyableExample',
+    selectorSuggestions: 'selectorSuggestion',
+    serviceSuggestions: 'serviceSuggestion',
+    repositories: 'repository',
+    examples: 'example',
+    expandedExamples: 'expandedExample',
+    registrations: 'registration',
+  };
+  return stems[key] ?? 'candidate';
+}
+
+function numericValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function upperFirst(value: string): string {
+  return value ? `${value[0]?.toUpperCase() ?? ''}${value.slice(1)}` : value;
+}