@saptools/service-flow 0.1.51 → 0.1.53

package/src/trace/trace-engine.ts

@@ -1,15 +1,34 @@
 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, runtimeResolution, runtimeVariableDiagnostic, type TraceGraphRow } from './evidence.js';
+import { baseTraceEvidence, edgeTarget, runtimeNoCandidateDiagnostics, runtimeResolution, runtimeVariableDiagnostic, type TraceGraphRow } from './evidence.js';
 import { dynamicCandidateBranches } from './dynamic-branches.js';
-import { implementationHintDiagnostic, selectImplementation, type ImplementationSelection } from './implementation-hints.js';
-import { ambiguousStartDiagnostic } from './selectors.js';
+import {
+  loadTraceDiagnostics,
+  prependTraceDiagnostic,
+} from './002-trace-diagnostics.js';
+import { implementationHintDiagnostic } from './implementation-hints.js';
+import {
+  contextualImplementationSelection,
+  hintedImplementationSelection,
+} from './005-implementation-selection.js';
+import { boundedContextCandidates } from './006-contextual-projection.js';
+import { implementationStartDiagnostic } from './007-implementation-start-diagnostic.js';
+import { boundCandidateLikeEvidence } from '../utils/000-bounded-projection.js';
+import {
+  ambiguousStartDiagnostic,
+  selectorNotFoundDiagnostic,
+  selectorRepoAmbiguousDiagnostic,
+  selectorRepoNotFoundDiagnostic,
+  sourceScopeForSelector,
+} from './selectors.js';
 interface RepoRef {
   id: number;
   name: string;
+  packageName?: string;
 }
 interface StartScope {
   repo?: RepoRef;
@@ -78,13 +97,14 @@ function normalizeOperation(value: string | undefined): string | undefined {
 function positiveDepth(value: number): number {
   return Number.isFinite(value) && value > 0 ? Math.floor(value) : 25;
 }
-function operationStartScope(db: Db, repoId: number | undefined, start: TraceStart, hintOptions: ImplementationHintOptions): { files?: Set<string>; symbols?: Set<number>; repoId?: number; operationId?: string; diagnostics?: Array<Record<string, unknown>> } | undefined {
+function operationStartScope(db: Db, repoId: number | undefined, start: TraceStart, hintOptions: ImplementationHintOptions, workspaceId?: number): { files?: Set<string>; symbols?: Set<number>; repoId?: number; operationId?: string; diagnostics?: Array<Record<string, unknown>> } | undefined {
   const requested = normalizeOperation(start.operationPath ?? start.operation);
   if (!requested) return undefined;
   const rows = db.prepare(`SELECT o.id operationId,o.operation_name operationName,o.operation_path operationPath,o.source_file sourceFile,o.source_line sourceLine,s.service_path servicePath,r.id repoId,r.name repoName
     FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id
-    WHERE (? IS NULL OR r.id=?) AND (? IS NULL OR s.service_path=?) AND (o.operation_name=? OR o.operation_path=? OR o.operation_path=?)
-    ORDER BY r.name,s.service_path,o.operation_name,o.id`).all(repoId, repoId, start.servicePath, start.servicePath, requested, requested, requested.startsWith('/') ? requested : `/${requested}`) as Array<Record<string, unknown>>;
+    WHERE (? IS NULL OR r.workspace_id=?) AND (? IS NULL OR r.id=?)
+      AND (? IS NULL OR s.service_path=?) AND (o.operation_name=? OR o.operation_path=? OR o.operation_path=?)
+    ORDER BY r.name,s.service_path,o.operation_name,o.id`).all(workspaceId, workspaceId, repoId, repoId, start.servicePath, start.servicePath, requested, requested, requested.startsWith('/') ? requested : `/${requested}`) as Array<Record<string, unknown>>;
   if (rows.length === 0) return undefined;
   const repoCount = new Set(rows.map((row) => String(row.repoName))).size;
   const serviceCount = new Set(rows.map((row) => `${String(row.repoName)}:${String(row.servicePath)}`)).size;
@@ -97,89 +117,52 @@ 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,
   start: TraceStart,
-): { files?: Set<string>; symbols?: Set<number>; repoId?: number } | undefined {
-  const handler = start.handler;
-  const operation = normalizeOperation(start.operation ?? start.operationPath);
-  if (!handler && !operation) return undefined;
-  const rows = db
-    .prepare(
-      `SELECT DISTINCT hc.source_file sourceFile,s.id symbolId
-       FROM handler_classes hc LEFT JOIN handler_methods hm ON hm.handler_class_id=hc.id LEFT JOIN symbols s ON s.repo_id=hc.repo_id AND s.source_file=hc.source_file AND s.name=hm.method_name
-       WHERE (? IS NULL OR hc.repo_id=?) AND (? IS NULL OR hc.class_name=? OR hm.method_name=?)
-         AND (? IS NULL OR hm.decorator_value=? OR hm.method_name=?)
-         AND (? IS NULL OR EXISTS (SELECT 1 FROM cds_services s JOIN cds_operations o ON o.service_id=s.id WHERE s.repo_id=hc.repo_id AND s.service_path=? AND (? IS NULL OR o.operation_path=? OR o.operation_name=? OR hm.decorator_value=? OR hm.method_name=?)))`,
-    )
-    .all(
-      repoId,
-      repoId,
-      handler,
-      handler,
-      handler,
-      operation,
-      operation,
-      operation,
-      start.servicePath,
-      start.servicePath,
-      operation,
-      operation,
-      operation,
-      operation,
-      operation,
-    ) as Array<{ sourceFile?: string; symbolId?: number }>;
-  if (rows.length > 0) return { files: new Set(rows.map((row) => row.sourceFile).filter(Boolean) as string[]), symbols: new Set(rows.map((row) => Number(row.symbolId)).filter(Boolean)), repoId };
-  if (start.servicePath && operation) {
-    const implRows = db.prepare(`SELECT DISTINCT hc.source_file sourceFile,sym.id symbolId
-      FROM cds_services s JOIN cds_operations o ON o.service_id=s.id
-      JOIN graph_edges e ON e.edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND e.status='resolved' AND e.from_kind='operation' AND e.from_id=CAST(o.id AS TEXT)
-      JOIN handler_methods hm ON hm.id=CAST(e.to_id AS INTEGER)
-      JOIN handler_classes hc ON hc.id=hm.handler_class_id
-      LEFT JOIN symbols sym ON sym.repo_id=hc.repo_id AND sym.source_file=hc.source_file AND sym.name=hm.method_name
-      WHERE (? IS NULL OR s.repo_id=?) AND s.service_path=? AND (o.operation_path=? OR o.operation_name=?)`).all(repoId, repoId, start.servicePath, operation, operation) as Array<{ sourceFile?: string; symbolId?: number }>;
-    if (implRows.length > 0) return { files: new Set(implRows.map((row) => row.sourceFile).filter(Boolean) as string[]), symbols: new Set(implRows.map((row) => Number(row.symbolId)).filter(Boolean)), repoId };
-  }
-  return undefined;
-}
-function startScope(db: Db, start: TraceStart, hintOptions: ImplementationHintOptions): StartScope {
-  const repo = start.repo
-    ? (db
-        .prepare(
-          'SELECT id,name FROM repositories WHERE name=? OR package_name=?',
-        )
-        .get(start.repo, start.repo) as RepoRef | undefined)
-    : undefined;
-  if (start.repo && !repo) return { repo, selectorMatched: false };
-  const operationScope = operationStartScope(db, repo?.id, start, hintOptions);
+  workspaceId: number | undefined,
+): ReturnType<typeof sourceScopeForSelector> {
+  return sourceScopeForSelector(db, repoId, start, workspaceId);
+}
+function startScope(db: Db, start: TraceStart, hintOptions: ImplementationHintOptions, workspaceId?: number): StartScope {
+  const repos: RepoRef[] = start.repo
+    ? reposByName(db, start.repo, workspaceId).map((row) => ({
+        id: row.id,
+        name: row.name,
+        packageName: row.package_name ?? undefined,
+      }))
+    : [];
+  if (start.repo && repos.length === 0) return {
+    selectorMatched: false,
+    startDiagnostics: [selectorRepoNotFoundDiagnostic(start.repo)],
+  };
+  if (start.repo && repos.length > 1) return {
+    selectorMatched: false,
+    startDiagnostics: [selectorRepoAmbiguousDiagnostic(start.repo, repos)],
+  };
+  const repo = repos[0];
+  const operationScope = operationStartScope(
+    db, repo?.id, start, hintOptions, workspaceId,
+  );
   const terminalOperationScope = operationScope && !operationScope.files && (operationScope.diagnostics ?? []).some((d) => d.resolutionStage === 'operation' || d.resolutionStage === 'implementation');
-  const sourceScope = operationScope?.files || terminalOperationScope ? operationScope : sourceFilesForStart(db, repo?.id, start);
+  const sourceScope = operationScope?.files || terminalOperationScope ? operationScope : sourceFilesForStart(db, repo?.id, start, workspaceId);
+  const terminalSelectorScope = Boolean(sourceScope?.diagnostics?.length && !sourceScope.files);
   const sourceFiles = sourceScope?.files;
   const hasSelector = Boolean(
     start.handler ?? start.operation ?? start.operationPath ?? start.servicePath,
@@ -191,9 +174,12 @@ function startScope(db: Db, start: TraceStart, hintOptions: ImplementationHintOp
     executionRepoId: sourceScope?.repoId ?? repo?.id,
     sourceFiles,
     symbolIds: sourceScope?.symbols,
-    selectorMatched: !terminalOperationScope && (!hasSelector || sourceFiles !== undefined),
+    selectorMatched: !terminalOperationScope && !terminalSelectorScope
+      && (!hasSelector || sourceFiles !== undefined),
     startOperationId: operationScope?.operationId,
-    startDiagnostics: operationScope?.diagnostics,
+    startDiagnostics: operationScope?.diagnostics?.length
+      ? operationScope.diagnostics
+      : sourceScope?.diagnostics,
   };
 }
 function handlerFilesForOperation(db: Db, operationId: string): Set<string> {
@@ -211,8 +197,19 @@ function handlerFilesForOperation(db: Db, operationId: string): Set<string> {
     .prepare(
       `SELECT DISTINCT hc.source_file sourceFile,sym.id symbolId FROM handler_classes hc
     JOIN handler_methods hm ON hm.handler_class_id=hc.id
-    LEFT JOIN symbols sym ON sym.repo_id=hc.repo_id AND sym.source_file=hc.source_file AND sym.name=hm.method_name
-    WHERE hc.repo_id=? AND (hm.decorator_value=? OR hm.method_name=? OR hm.decorator_value=?)`,
+    LEFT JOIN symbols sym ON sym.repo_id=hc.repo_id
+      AND sym.source_file=hc.source_file
+      AND sym.qualified_name=hc.class_name || '.' || hm.method_name
+      AND sym.start_line=hm.source_line
+    WHERE hc.repo_id=?
+      AND COALESCE(json_extract(hm.decorator_resolution_json,'$.handlerKind'),
+        CASE WHEN hm.decorator_kind='Event' THEN 'event'
+          WHEN hm.decorator_kind IN ('Action','Func','On') THEN 'operation'
+          ELSE 'unsupported' END)='operation'
+      AND COALESCE(json_extract(hm.decorator_resolution_json,'$.executable'),
+        CASE WHEN hm.decorator_kind IN ('Action','Func','On')
+          THEN 1 ELSE 0 END)=1
+      AND (hm.decorator_value=? OR hm.method_name=? OR hm.decorator_value=?)`,
     )
     .all(op.repoId, operation, operation, op.operationName) as Array<{
     sourceFile?: string;
@@ -230,35 +227,14 @@ function handlerMethodNode(db: Db, methodId: string): Record<string, unknown> |
 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 };
-  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.name=hm.method_name WHERE hm.id=?').get(edge.to_id) as { repoId?: number; sourceFile?: 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(edge.to_id) as { repoId?: number; sourceFile?: string; symbolId?: number } | undefined;
+  if (!row || typeof row.symbolId !== 'number')
+    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.name=hm.method_name WHERE hm.id=?').get(methodId) as { repoId?: number; sourceFile?: string; symbolId?: number } | undefined;
-  if (!row) return 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;
   return { repoId: row.repoId, files: new Set(row.sourceFile ? [row.sourceFile] : []), symbolId: row.symbolId };
 }
 
@@ -315,11 +291,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;
@@ -459,16 +439,20 @@ function contextForSymbolCall(db: Db, symbolCall: Record<string, unknown>, calle
 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') {
+    const candidates = boundedContextCandidates(binding.bindingCandidates ?? []);
     return {
       evidence: {
         contextualServiceBindingAttempted: true,
         contextualBinding: {
           source: binding.source,
           status: 'tied',
-          candidates: binding.bindingCandidates,
+          candidates: candidates.candidates,
+          candidateCount: candidates.candidateCount,
+          shownCandidateCount: candidates.shownCandidateCount,
+          omittedCandidateCount: candidates.omittedCandidateCount,
         },
         contextualResolutionStatus: 'ambiguous',
-        contextualCandidateCount: binding.bindingCandidates?.length ?? 0,
+        contextualCandidateCount: candidates.candidateCount,
       },
       unresolvedReason: 'Ambiguous contextual service binding candidates',
     };
@@ -478,7 +462,8 @@ function contextualRuntimeResolution(db: Db, call: CallRow, binding: ContextBind
   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 };
+  const candidates = boundedContextCandidates(resolution.candidates);
+  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: candidates.candidateCount, shownContextualCandidateCount: candidates.shownCandidateCount, omittedContextualCandidateCount: candidates.omittedCandidateCount, candidates: candidates.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');
@@ -491,22 +476,25 @@ export function trace(
   options: TraceOptions,
 ): TraceResult {
   const hintOptions = { implementationRepo: options.implementationRepo, implementationHints: options.implementationHints };
-  const scope = startScope(db, start, hintOptions);
-  const diagnostics = db
-    .prepare(
-      'SELECT severity,code,message,source_file sourceFile,source_line sourceLine FROM diagnostics WHERE (? IS NULL OR repo_id=?)',
-    )
-    .all(scope.repo?.id, scope.repo?.id) as Array<Record<string, unknown>>;
-  const stale = db.prepare('SELECT name,graph_stale_reason reason FROM repositories WHERE graph_stale_reason IS NOT NULL AND (? IS NULL OR id=?)').all(scope.repo?.id, scope.repo?.id) as Array<{ name?: string; reason?: string }>;
+  const scope = startScope(db, start, hintOptions, options.workspaceId);
+  const hasSelector = Boolean(start.repo || start.handler || start.operation
+    || start.operationPath || start.servicePath);
+  const diagnosticRepoId = scope.executionRepoId ?? scope.repo?.id;
+  const diagnostics = loadTraceDiagnostics(
+    db,
+    diagnosticRepoId,
+    !hasSelector,
+    options.workspaceId,
+  );
+  const stale = diagnosticRepoId !== undefined || !hasSelector
+    ? db.prepare('SELECT name,graph_stale_reason reason FROM repositories WHERE graph_stale_reason IS NOT NULL AND (? IS NULL OR id=?) AND (? IS NULL OR workspace_id=?) ORDER BY name,id').all(diagnosticRepoId, diagnosticRepoId, options.workspaceId, options.workspaceId) as Array<{ name?: string; reason?: string }>
+    : [];
   for (const row of stale)
-    diagnostics.unshift({ severity: 'warning', code: 'graph_stale', message: `Graph is stale for ${row.name ?? 'repository'}: ${row.reason ?? 'facts_changed'}. Run service-flow link.` });
-  for (const diagnostic of scope.startDiagnostics ?? []) diagnostics.unshift(diagnostic);
+    prependTraceDiagnostic(diagnostics, { severity: 'warning', code: 'graph_stale', message: `Graph is stale for ${row.name ?? 'repository'}: ${row.reason ?? 'facts_changed'}. Run service-flow link.` });
+  for (const diagnostic of scope.startDiagnostics ?? [])
+    prependTraceDiagnostic(diagnostics, diagnostic);
   if (!scope.selectorMatched && !(scope.startDiagnostics?.length))
-    diagnostics.unshift({
-      severity: 'warning',
-      code: 'trace_start_not_found',
-      message: start.servicePath && !start.operation && !start.operationPath && !start.handler ? 'Service-only trace requires --operation or --path and will not broaden to the whole workspace' : 'No handler source matched the requested trace start selector',
-    });
+    prependTraceDiagnostic(diagnostics, selectorNotFoundDiagnostic(start));
   const maxDepth = positiveDepth(options.depth);
   const edges: TraceEdge[] = [];
   const nodes = new Map<string, Record<string, unknown>>();
@@ -519,7 +507,9 @@ 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 };
@@ -539,9 +529,9 @@ export function trace(
     seenScopes.add(key);
     const calls = db
       .prepare(
-        `SELECT c.*,r.name repoName FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE (? IS NULL OR c.repo_id=?) ORDER BY c.source_file,c.source_line`,
+        `SELECT c.*,r.name repoName FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE (? IS NULL OR c.repo_id=?) AND (? IS NULL OR r.workspace_id=?) ORDER BY c.source_file,c.source_line`,
       )
-      .all(current.repoId, current.repoId) as CallRow[];
+      .all(current.repoId, current.repoId, options.workspaceId, options.workspaceId) as CallRow[];
     const filtered = calls.filter(
       (c) =>
         (!current.symbolIds || current.symbolIds.has(Number(c.source_symbol_id))) && (!current.files || current.files.has(String(c.source_file))) &&
@@ -559,7 +549,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) });
@@ -585,9 +575,7 @@ 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,
@@ -613,17 +601,21 @@ 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;
           if (implementation.edge) {
-            const implEvidence = JSON.parse(String(implementation.edge.evidence_json || '{}')) as Record<string, unknown>;
-            const hintDiagnostic = implementationHintDiagnostic(contextSelection, implEvidence.implementationHintSuggestions);
-            if (hintDiagnostic) diagnostics.unshift(hintDiagnostic);
+            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);
@@ -674,6 +666,8 @@ export function trace(
     }
   }
   const runtimeDiagnostic = runtimeVariableDiagnostic(edges);
-  if (runtimeDiagnostic) diagnostics.unshift(runtimeDiagnostic);
+  if (runtimeDiagnostic) prependTraceDiagnostic(diagnostics, runtimeDiagnostic);
+  for (const diagnostic of runtimeNoCandidateDiagnostics(edges))
+    prependTraceDiagnostic(diagnostics, diagnostic);
   return { start, nodes: [...nodes.values()], edges, diagnostics };
 }

package/src/types.ts

@@ -95,14 +95,34 @@ export interface HandlerClassFact {
   sourceFile: string;
   sourceLine: number;
   methods: HandlerMethodFact[];
-}
+  hasHandlerDecorator?: boolean;
+  classDecoratorNames?: string[];
+  observedDecoratorNames?: string[];
+  unsupportedDecoratorNames?: string[];
+}
+export type HandlerMethodKind =
+  | 'operation'
+  | 'entity_lifecycle'
+  | 'event'
+  | 'unsupported_lifecycle'
+  | 'unsupported_decorator';
+export type HandlerLifecyclePhase = 'on' | 'before' | 'after';
+export type HandlerLifecycleEvent = 'CREATE' | 'READ' | 'UPDATE' | 'DELETE';
 export interface HandlerMethodFact {
   methodName: string;
   decoratorKind: string;
   decoratorValue?: string;
   decoratorRawExpression: string;
+  handlerKind?: HandlerMethodKind;
+  executable?: boolean;
+  lifecyclePhase?: HandlerLifecyclePhase;
+  lifecycleEvent?: HandlerLifecycleEvent;
   decoratorResolution: {
     rawExpression: string;
+    decoratorExpression?: string;
+    argumentExpression?: string;
+    resolvedDecoratorKind?: string;
+    decoratorImportSource?: string;
     resolvedValue?: string;
     resolutionKind:
       | 'literal'
@@ -110,8 +130,13 @@ export interface HandlerMethodFact {
       | 'enum_member'
       | 'const_object_property'
       | 'generated_constant_name'
+      | 'lifecycle_implicit'
       | 'unresolved';
     unresolvedReason?: string;
+    handlerKind?: HandlerMethodKind;
+    executable?: boolean;
+    lifecyclePhase?: HandlerLifecyclePhase;
+    lifecycleEvent?: HandlerLifecycleEvent;
   };
   sourceFile: string;
   sourceLine: number;
@@ -202,6 +227,7 @@ export interface ImplementationHint {
 export type DynamicMode = 'strict' | 'candidates' | 'infer';
 export interface TraceOptions {
   depth: number;
+  workspaceId?: number;
   vars?: Record<string, string>;
   includeExternal?: boolean;
   includeDb?: boolean;