@saptools/service-flow 0.1.50 → 0.1.51

package/src/trace/dynamic-targets.ts

@@ -0,0 +1,424 @@
+import type { Db } from '../db/connection.js';
+import { extractPlaceholders } from '../linker/dynamic-edge-resolver.js';
+import type { OperationTarget } from '../linker/service-resolver.js';
+import type { DynamicMode } from '../types.js';
+
+export interface DynamicTargetCandidate {
+  candidateOperationId: number;
+  repoName: string;
+  packageName?: string;
+  servicePath: string;
+  operationPath: string;
+  operationName: string;
+  derivedVariables: Record<string, string>;
+  derivedVariableSources: Record<string, Record<string, unknown>>;
+  missingVariables: string[];
+  score: number;
+  reasons: string[];
+  rejectedReasons: string[];
+  cli?: string;
+}
+
+export interface DynamicTargetAnalysis {
+  mode: DynamicMode;
+  candidateCount: number;
+  shownCandidateCount: number;
+  omittedCandidateCount: number;
+  missingVariables: string[];
+  candidates: DynamicTargetCandidate[];
+  shownCandidates: DynamicTargetCandidate[];
+  suggestedVarSets: Array<{ variables: Record<string, string>; cli: string }>;
+  inference: Record<string, unknown>;
+}
+
+interface ReferenceRow {
+  alias?: string;
+  destination?: string;
+  servicePath?: string;
+  sourceKind: string;
+  repoName: string;
+}
+
+interface Templates {
+  servicePath?: string;
+  operationPath?: string;
+  alias?: string;
+  destination?: string;
+}
+
+export function analyzeDynamicTargetCandidates(
+  db: Db,
+  evidence: Record<string, unknown>,
+  workspaceId: number | undefined,
+  mode: DynamicMode,
+  maxCandidates: number,
+): DynamicTargetAnalysis | undefined {
+  const templates = templatesFromEvidence(evidence);
+  const missingVariables = allMissingVariables(evidence, templates);
+  if (missingVariables.length === 0) return undefined;
+  const order = variableOrder(templates, missingVariables);
+  const candidates = rankedCandidates(
+    db,
+    candidateTargets(db, evidence, workspaceId),
+    referenceRows(db, workspaceId),
+    templates,
+    order,
+  );
+  const inference = inferenceDecision(candidates);
+  const shownCandidates = candidates.slice(0, maxCandidates);
+  return {
+    mode,
+    candidateCount: candidates.length,
+    shownCandidateCount: shownCandidates.length,
+    omittedCandidateCount: Math.max(0, candidates.length - shownCandidates.length),
+    missingVariables,
+    candidates,
+    shownCandidates,
+    suggestedVarSets: suggestedVarSets(candidates, missingVariables, order),
+    inference,
+  };
+}
+
+function candidateTargets(
+  db: Db,
+  evidence: Record<string, unknown>,
+  workspaceId: number | undefined,
+): OperationTarget[] {
+  const embedded = rowsFromEvidence(evidence.candidates);
+  if (embedded.length > 0) return embedded;
+  const operationPath = stringValue(evidence.operationPath);
+  if (!operationPath || extractPlaceholders(operationPath).length > 0) return [];
+  return queryOperationTargets(db, operationPath, workspaceId);
+}
+
+function rowsFromEvidence(value: unknown): OperationTarget[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item): OperationTarget[] => {
+    const row = record(item);
+    const operationId = numberValue(row.operationId);
+    const repoName = stringValue(row.repoName);
+    const servicePath = stringValue(row.servicePath);
+    const operationPath = stringValue(row.operationPath);
+    const operationName = stringValue(row.operationName) ?? operationPath?.replace(/^\//, '');
+    if (operationId === undefined || !repoName || !servicePath || !operationPath || !operationName) return [];
+    return [{
+      operationId,
+      repoName,
+      serviceName: stringValue(row.serviceName) ?? '',
+      qualifiedName: stringValue(row.qualifiedName) ?? '',
+      servicePath,
+      operationPath,
+      operationName,
+      sourceFile: stringValue(row.sourceFile) ?? '',
+      sourceLine: numberValue(row.sourceLine) ?? 0,
+      repoId: numberValue(row.repoId),
+      packageName: stringValue(row.packageName),
+      score: numberValue(row.score) ?? 0,
+      reasons: stringArray(row.reasons),
+    }];
+  });
+}
+
+function queryOperationTargets(
+  db: Db,
+  operationPath: string,
+  workspaceId: number | undefined,
+): OperationTarget[] {
+  const simple = operationPath.replace(/^\//, '').split('.').at(-1) ?? operationPath;
+  const rows = db.prepare(
+    `SELECT o.id operationId,r.id repoId,r.name repoName,r.package_name packageName,
+      s.service_name serviceName,s.qualified_name qualifiedName,s.service_path servicePath,
+      o.operation_path operationPath,o.operation_name operationName,o.source_file sourceFile,
+      o.source_line sourceLine
+     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.workspace_id=?)
+       AND (o.operation_path IN (?,?) OR o.operation_name=?)
+     ORDER BY r.name,s.service_path,o.operation_name`,
+  ).all(workspaceId, workspaceId, operationPath, `/${simple}`, simple) as Array<Record<string, unknown>>;
+  return rows.map((row) => ({
+    operationId: Number(row.operationId),
+    repoId: numberValue(row.repoId),
+    repoName: String(row.repoName),
+    packageName: stringValue(row.packageName),
+    serviceName: String(row.serviceName),
+    qualifiedName: String(row.qualifiedName),
+    servicePath: String(row.servicePath),
+    operationPath: String(row.operationPath),
+    operationName: String(row.operationName),
+    sourceFile: String(row.sourceFile),
+    sourceLine: Number(row.sourceLine),
+    score: 0.2,
+    reasons: ['operation_path_match'],
+  }));
+}
+
+function rankedCandidates(
+  db: Db,
+  candidates: OperationTarget[],
+  references: ReferenceRow[],
+  templates: Templates,
+  order: string[],
+): DynamicTargetCandidate[] {
+  const ranked = candidates.map((candidate) =>
+    candidateEvidence(db, candidate, references, templates, order));
+  return ranked.sort((a, b) =>
+    b.score - a.score
+    || a.repoName.localeCompare(b.repoName)
+    || a.servicePath.localeCompare(b.servicePath));
+}
+
+function candidateEvidence(
+  db: Db,
+  candidate: OperationTarget,
+  references: ReferenceRow[],
+  templates: Templates,
+  order: string[],
+): DynamicTargetCandidate {
+  const state = emptyCandidate(candidate);
+  applyDirectTemplate(state, templates.operationPath, candidate.operationPath, 'operation_path');
+  applyDirectTemplate(state, templates.servicePath, candidate.servicePath, 'service_path');
+  const refs = references.filter((item) => item.servicePath === candidate.servicePath);
+  applyReferenceTemplate(state, templates.alias, refs, 'alias');
+  applyReferenceTemplate(state, templates.destination, refs, 'destination');
+  if (hasResolvedImplementation(db, candidate.operationId)) addScore(state, 0.1, 'implementation_edge_resolved');
+  state.missingVariables = order.filter((key) => state.derivedVariables[key] === undefined);
+  if (state.missingVariables.length === 0) addScore(state, 0.15, 'all_runtime_variables_derived');
+  else state.rejectedReasons.push('missing_required_runtime_variable');
+  state.score = Math.max(0, Math.min(1, state.score));
+  state.cli = state.missingVariables.length === 0 ? cliFor(state.derivedVariables, order) : undefined;
+  return state;
+}
+
+function emptyCandidate(candidate: OperationTarget): DynamicTargetCandidate {
+  return {
+    candidateOperationId: candidate.operationId,
+    repoName: candidate.repoName,
+    packageName: candidate.packageName ?? undefined,
+    servicePath: candidate.servicePath,
+    operationPath: candidate.operationPath,
+    operationName: candidate.operationName,
+    derivedVariables: {},
+    derivedVariableSources: {},
+    missingVariables: [],
+    score: Math.max(0.2, Number(candidate.score ?? 0)),
+    reasons: nonEmptyStrings(candidate.reasons, ['operation_path_match']),
+    rejectedReasons: [],
+  };
+}
+
+function applyDirectTemplate(
+  state: DynamicTargetCandidate,
+  template: string | undefined,
+  concrete: string,
+  kind: 'operation_path' | 'service_path',
+): void {
+  const matched = matchTemplate(template, concrete);
+  if (!template) return;
+  if (!matched) {
+    state.rejectedReasons.push(`${kind}_template_mismatch`);
+    return;
+  }
+  mergeDerived(state, matched, `${kind}_template`);
+  addScore(state, kind === 'service_path' ? 0.35 : 0.25, `${kind}_template_match`);
+}
+
+function applyReferenceTemplate(
+  state: DynamicTargetCandidate,
+  template: string | undefined,
+  refs: ReferenceRow[],
+  kind: 'alias' | 'destination',
+): void {
+  if (!template || extractPlaceholders(template).length === 0) return;
+  for (const ref of refs) {
+    const concrete = kind === 'alias' ? ref.alias : ref.destination;
+    const matched = isConcrete(concrete) ? matchTemplate(template, concrete) : undefined;
+    if (!matched) continue;
+    mergeDerived(state, matched, `${ref.sourceKind}.${kind}`);
+    addScore(state, 0.2, `${kind}_template_match`);
+    return;
+  }
+  if (refs.some((ref) => isConcrete(kind === 'alias' ? ref.alias : ref.destination)))
+    state.rejectedReasons.push(`${kind}_template_mismatch`);
+}
+
+function inferenceDecision(candidates: DynamicTargetCandidate[]): Record<string, unknown> {
+  const complete = candidates.filter((candidate) =>
+    candidate.missingVariables.length === 0
+    && candidate.rejectedReasons.length === 0);
+  const first = complete[0];
+  const second = complete[1];
+  if (!first) return { status: 'unresolved', reason: 'missing_required_runtime_variable' };
+  if (first.score < 0.85) return { status: 'unresolved', reason: 'candidate_score_below_inference_threshold' };
+  if (second && first.score - second.score <= 0.05) {
+    for (const candidate of complete.filter((item) => first.score - item.score <= 0.05))
+      candidate.rejectedReasons.push('candidate_tied_with_equal_score');
+    return { status: 'ambiguous', reason: 'candidate_tied_with_equal_score' };
+  }
+  return {
+    status: 'resolved',
+    candidateOperationId: first.candidateOperationId,
+    inferredVariables: first.derivedVariables,
+    score: first.score,
+    reasons: first.reasons,
+  };
+}
+
+function suggestedVarSets(
+  candidates: DynamicTargetCandidate[],
+  required: string[],
+  order: string[],
+): Array<{ variables: Record<string, string>; cli: string }> {
+  const seen = new Set<string>();
+  return candidates.flatMap((candidate) => {
+    if (required.some((key) => candidate.derivedVariables[key] === undefined)) return [];
+    const cli = cliFor(candidate.derivedVariables, order);
+    if (seen.has(cli)) return [];
+    seen.add(cli);
+    return [{ variables: candidate.derivedVariables, cli }];
+  });
+}
+
+function referenceRows(db: Db, workspaceId: number | undefined): ReferenceRow[] {
+  const rows = db.prepare(
+    `SELECT req.alias alias,req.destination destination,req.service_path servicePath,
+      'cds_require' sourceKind,r.name repoName
+     FROM cds_requires req JOIN repositories r ON r.id=req.repo_id
+     WHERE (? IS NULL OR r.workspace_id=?)
+     UNION ALL
+     SELECT COALESCE(b.alias,b.alias_expr) alias,b.destination_expr destination,
+      b.service_path_expr servicePath,'service_binding' sourceKind,r.name repoName
+     FROM service_bindings b JOIN repositories r ON r.id=b.repo_id
+     WHERE (? IS NULL OR r.workspace_id=?)`,
+  ).all(workspaceId, workspaceId, workspaceId, workspaceId) as Array<Record<string, unknown>>;
+  return rows.map((row) => ({
+    alias: stringValue(row.alias),
+    destination: stringValue(row.destination),
+    servicePath: stringValue(row.servicePath),
+    sourceKind: String(row.sourceKind),
+    repoName: String(row.repoName),
+  }));
+}
+
+function allMissingVariables(evidence: Record<string, unknown>, templates: Templates): string[] {
+  const fromSubstitutions = Object.values(record(evidence.runtimeSubstitutions))
+    .flatMap((value) => stringArray(record(value).missing));
+  const fromTemplates = [
+    templates.servicePath,
+    templates.operationPath,
+    templates.alias,
+    templates.destination,
+  ].flatMap((value) => extractPlaceholders(value));
+  return [...new Set([...fromSubstitutions, ...fromTemplates])].sort();
+}
+
+function variableOrder(templates: Templates, missingVariables: string[]): string[] {
+  const ordered = [
+    templates.servicePath,
+    templates.operationPath,
+    templates.alias,
+    templates.destination,
+  ].flatMap((value) => extractPlaceholders(value));
+  return [...new Set([...ordered, ...missingVariables])];
+}
+
+function templatesFromEvidence(evidence: Record<string, unknown>): Templates {
+  return {
+    servicePath: stringValue(evidence.servicePath),
+    operationPath: stringValue(evidence.operationPath),
+    alias: stringValue(evidence.serviceAliasExpr ?? evidence.serviceAlias),
+    destination: stringValue(evidence.destination),
+  };
+}
+
+function matchTemplate(template: string | undefined, concrete: string | undefined): Record<string, string> | undefined {
+  if (!template || !concrete) return undefined;
+  const keys = extractPlaceholders(template);
+  if (keys.length === 0) return template === concrete ? {} : undefined;
+  const regex = new RegExp(`^${templateToPattern(template)}$`);
+  const match = regex.exec(concrete);
+  if (!match) return undefined;
+  const values: Record<string, string> = {};
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index];
+    const value = match[index + 1];
+    if (!key || value === undefined) return undefined;
+    if (values[key] !== undefined && values[key] !== value) return undefined;
+    values[key] = value;
+  }
+  return values;
+}
+
+function templateToPattern(template: string): string {
+  let pattern = '';
+  let lastIndex = 0;
+  for (const match of template.matchAll(/\$\{([^}]*)\}/g)) {
+    pattern += escapeRegex(template.slice(lastIndex, match.index));
+    pattern += '([^/]+?)';
+    lastIndex = (match.index ?? 0) + match[0].length;
+  }
+  return `${pattern}${escapeRegex(template.slice(lastIndex))}`;
+}
+
+function mergeDerived(
+  state: DynamicTargetCandidate,
+  values: Record<string, string>,
+  sourceKind: string,
+): void {
+  for (const [key, value] of Object.entries(values)) {
+    if (state.derivedVariables[key] !== undefined && state.derivedVariables[key] !== value) {
+      state.rejectedReasons.push('template_variable_conflict');
+      continue;
+    }
+    state.derivedVariables[key] = value;
+    state.derivedVariableSources[key] = { sourceKind, value };
+  }
+}
+
+function addScore(state: DynamicTargetCandidate, amount: number, reason: string): void {
+  state.score += amount;
+  if (!state.reasons.includes(reason)) state.reasons.push(reason);
+}
+
+function hasResolvedImplementation(db: Db, operationId: number): boolean {
+  const row = db.prepare(
+    "SELECT 1 FROM graph_edges WHERE edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND status='resolved' AND from_kind='operation' AND from_id=? LIMIT 1",
+  ).get(String(operationId));
+  return Boolean(row);
+}
+
+function cliFor(variables: Record<string, string>, order: string[]): string {
+  return order
+    .filter((key) => variables[key] !== undefined)
+    .map((key) => `--var ${key}=${variables[key]}`)
+    .join(' ');
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
+function nonEmptyStrings(value: unknown, fallback: string[]): string[] {
+  const values = stringArray(value).filter((item) => item.length > 0);
+  return values.length > 0 ? values : fallback;
+}
+
+function isConcrete(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && extractPlaceholders(value).length === 0;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/trace/evidence.ts

@@ -2,6 +2,8 @@ import type { Db } from '../db/connection.js';
 import { extractPlaceholders, substituteVariables, type RuntimeSubstitution } from '../linker/dynamic-edge-resolver.js';
 import { normalizeODataOperationInvocationPath } from '../linker/odata-path-normalizer.js';
 import { resolveOperation, type OperationTarget } from '../linker/service-resolver.js';
+import type { DynamicMode } from '../types.js';
+import { analyzeDynamicTargetCandidates, type DynamicTargetAnalysis, type DynamicTargetCandidate } from './dynamic-targets.js';
 
 export interface TraceGraphRow extends Record<string, unknown> {
   id: number;
@@ -50,27 +52,49 @@ export function runtimeResolution(
   db: Db,
   row: TraceGraphRow,
   evidence: Record<string, unknown>,
-  vars: Record<string, string> | undefined,
+  options: { vars?: Record<string, string>; dynamicMode?: DynamicMode; maxDynamicCandidates?: number },
   workspaceId: number | undefined,
   contextualUnresolvedReason?: string,
 ): { row: TraceGraphRow; evidence: Record<string, unknown>; target?: OperationTarget; unresolvedReason?: string } {
-  const substituted = evidenceWithRuntimeVariables(evidence, vars);
-  if (!isRemoteRuntimeCandidate(row, evidence, vars)) {
+  const substituted = evidenceWithRuntimeVariables(evidence, options.vars);
+  const dynamicMode = options.dynamicMode ?? 'strict';
+  const analysis = analyzeDynamicTargetCandidates(
+    db,
+    substituted,
+    workspaceId,
+    dynamicMode,
+    positiveCandidateCap(options.maxDynamicCandidates),
+  );
+  const enriched = analysis ? evidenceWithDynamicAnalysis(substituted, analysis) : substituted;
+  if (dynamicMode === 'infer') {
+    const inferred = inferredTarget(analysis);
+    if (inferred) {
+      const resolvedRow = { ...row, status: 'resolved', to_kind: 'operation', to_id: String(inferred.operationId), unresolved_reason: undefined, confidence: inferred.score };
+      const resolution = { status: 'resolved' as const, target: inferred, candidates: [], reasons: inferred.reasons };
+      return { row: resolvedRow, evidence: withEffectiveResolution(enriched, resolvedRow, undefined, resolution), target: inferred };
+    }
+  }
+  if (!isRemoteRuntimeCandidate(row, evidence, options.vars)) {
     const unresolvedReason = contextualUnresolvedReason ?? row.unresolved_reason;
-    const withSections = withEffectiveResolution(substituted, row, unresolvedReason);
+    const withSections = withEffectiveResolution(enriched, row, unresolvedReason);
     return { row, evidence: withSections, unresolvedReason };
   }
-  const resolution = resolveRuntimeOperation(db, substituted, workspaceId);
+  const resolution = resolveRuntimeOperation(db, enriched, workspaceId);
   if (resolution.target) {
     const resolvedRow = { ...row, status: 'resolved', to_kind: 'operation', to_id: String(resolution.target.operationId), unresolved_reason: undefined, confidence: Math.max(0, Math.min(1, resolution.target.score)) };
-    return { row: resolvedRow, evidence: withEffectiveResolution(substituted, resolvedRow, undefined, resolution), target: resolution.target };
+    return { row: resolvedRow, evidence: withEffectiveResolution(enriched, resolvedRow, undefined, resolution), target: resolution.target };
   }
   const unresolvedReason = runtimeUnresolvedReason(resolution);
-  return { row, evidence: withEffectiveResolution(substituted, row, unresolvedReason, resolution), unresolvedReason };
+  return { row, evidence: withEffectiveResolution(enriched, row, unresolvedReason, resolution), unresolvedReason };
 }
 
 export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string, unknown> }>): Record<string, unknown> | undefined {
   const missing = new Set<string>();
+  let candidateCount = 0;
+  let shownCandidateCount = 0;
+  let omittedCandidateCount = 0;
+  const candidateSuggestions: Record<string, unknown>[] = [];
+  const suggestedVarSets: Record<string, unknown>[] = [];
   for (const edge of edges) {
     const effective = parseObject(edge.evidence.effectiveResolution);
     if (!['dynamic', 'unresolved', 'ambiguous'].includes(String(effective.status ?? '')))
@@ -79,6 +103,12 @@ export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string
     if (!substitutions || typeof substitutions !== 'object' || Array.isArray(substitutions)) continue;
     for (const value of Object.values(substitutions as Record<string, RuntimeSubstitution>))
       for (const key of value.missing ?? []) missing.add(key);
+    const exploration = parseObject(edge.evidence.dynamicTargetExploration);
+    candidateCount += numeric(exploration.candidateCount);
+    shownCandidateCount += numeric(exploration.shownCandidateCount);
+    omittedCandidateCount += numeric(exploration.omittedCandidateCount);
+    candidateSuggestions.push(...recordArray(edge.evidence.dynamicTargetCandidateSuggestions));
+    suggestedVarSets.push(...recordArray(exploration.suggestedVarSets));
   }
   const missingVariables = [...missing].sort();
   if (missingVariables.length === 0) return undefined;
@@ -88,6 +118,16 @@ export function runtimeVariableDiagnostic(edges: Array<{ evidence: Record<string
     message: `Runtime variables are required to resolve dynamic trace targets: ${missingVariables.join(', ')}`,
     missingVariables,
     suggestions: missingVariables.map((key) => `--var ${key}=<value>`),
+    candidateCount,
+    shownCandidateCount,
+    omittedCandidateCount,
+    candidateSuggestions: candidateSuggestions.slice(0, 5),
+    suggestedVarSets: uniqueCliRows(suggestedVarSets).slice(0, 5),
+    copyableExamples: [
+      ...uniqueCliRows(suggestedVarSets).slice(0, 3).flatMap((row) =>
+        typeof row.cli === 'string' ? [row.cli] : []),
+      ...(candidateCount > 0 ? ['--dynamic-mode candidates --max-dynamic-candidates 20'] : []),
+    ],
   };
 }
 
@@ -180,6 +220,26 @@ function evidenceWithRuntimeVariables(evidence: Record<string, unknown>, vars: R
   return next;
 }
 
+function evidenceWithDynamicAnalysis(
+  evidence: Record<string, unknown>,
+  analysis: DynamicTargetAnalysis,
+): Record<string, unknown> {
+  return {
+    ...evidence,
+    dynamicTargetExploration: {
+      mode: analysis.mode,
+      missingVariables: analysis.missingVariables,
+      candidateCount: analysis.candidateCount,
+      shownCandidateCount: analysis.shownCandidateCount,
+      omittedCandidateCount: analysis.omittedCandidateCount,
+      suggestedVarSets: analysis.suggestedVarSets,
+    },
+    dynamicTargetCandidates: analysis.candidates,
+    dynamicTargetCandidateSuggestions: analysis.shownCandidates,
+    dynamicTargetInference: analysis.inference,
+  };
+}
+
 function runtimeSubstitutions(evidence: Record<string, unknown>, vars: Record<string, string>): Record<string, RuntimeSubstitution> {
   const substitutions: Record<string, RuntimeSubstitution> = {};
   for (const key of ['servicePath', 'operationPath', 'serviceAliasExpr', 'serviceAlias', 'destination']) {
@@ -206,6 +266,31 @@ function isRemoteRuntimeCandidate(row: TraceGraphRow, evidence: Record<string, u
   return ['servicePath', 'operationPath', 'serviceAliasExpr', 'serviceAlias', 'destination'].some((key) => hasRuntimeVariable(evidence[key], vars));
 }
 
+function inferredTarget(analysis: DynamicTargetAnalysis | undefined): OperationTarget | undefined {
+  if (analysis?.inference.status !== 'resolved') return undefined;
+  const id = Number(analysis.inference.candidateOperationId);
+  const candidate = analysis.candidates.find((item) => item.candidateOperationId === id);
+  if (!candidate) return undefined;
+  return targetFromCandidate(candidate);
+}
+
+function targetFromCandidate(candidate: DynamicTargetCandidate): OperationTarget {
+  return {
+    operationId: candidate.candidateOperationId,
+    repoName: candidate.repoName,
+    serviceName: '',
+    qualifiedName: '',
+    servicePath: candidate.servicePath,
+    operationPath: candidate.operationPath,
+    operationName: candidate.operationName,
+    packageName: candidate.packageName,
+    score: candidate.score,
+    reasons: candidate.reasons,
+    sourceFile: '',
+    sourceLine: 0,
+  };
+}
+
 function hasRuntimeVariable(value: unknown, vars: Record<string, string>): boolean {
   return typeof value === 'string' && extractPlaceholders(value).some((key) => Object.hasOwn(vars, key));
 }
@@ -223,3 +308,28 @@ function parseObject(value: unknown): Record<string, unknown> {
 function stringValue(value: unknown): string | undefined {
   return typeof value === 'string' ? value : undefined;
 }
+
+function numeric(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function recordArray(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> =>
+        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
+    : [];
+}
+
+function uniqueCliRows(rows: Record<string, unknown>[]): Record<string, unknown>[] {
+  const seen = new Set<string>();
+  return rows.filter((row) => {
+    const cli = typeof row.cli === 'string' ? row.cli : JSON.stringify(row);
+    if (seen.has(cli)) return false;
+    seen.add(cli);
+    return true;
+  });
+}
+
+function positiveCandidateCap(value: number | undefined): number {
+  return Number.isFinite(value) && Number(value) > 0 ? Math.floor(Number(value)) : 5;
+}

package/src/trace/trace-engine.ts

@@ -2,8 +2,9 @@ import type { Db } from '../db/connection.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, TraceResult, TraceStart } from '../types.js';
+import type { ImplementationHint, TraceEdge, TraceOptions, TraceResult, TraceStart } from '../types.js';
 import { baseTraceEvidence, edgeTarget, 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';
 interface RepoRef {
@@ -307,6 +308,7 @@ function operationNode(db: Db, operationId: string): Record<string, unknown> | u
   if (!row) return undefined;
   return { id: `operation:${operationId}`, kind: 'operation', label: `${String(row.repoName)}:${String(row.servicePath)}${String(row.operationPath)}`, ...row };
 }
+
 function workspaceIdForCall(db: Db, callId: string): number | undefined {
   return (db.prepare('SELECT r.workspace_id workspaceId FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE c.id=?').get(callId) as { workspaceId?: number } | undefined)?.workspaceId;
 }
@@ -486,15 +488,7 @@ function contextualRuntimeResolution(db: Db, call: CallRow, binding: ContextBind
 export function trace(
   db: Db,
   start: TraceStart,
-  options: {
-    depth: number;
-    vars?: Record<string, string>;
-    includeExternal?: boolean;
-    includeDb?: boolean;
-    includeAsync?: boolean;
-    implementationRepo?: string;
-    implementationHints?: ImplementationHint[];
-  },
+  options: TraceOptions,
 ): TraceResult {
   const hintOptions = { implementationRepo: options.implementationRepo, implementationHints: options.implementationHints };
   const scope = startScope(db, start, hintOptions);
@@ -595,7 +589,11 @@ export function trace(
           String(row.evidence_json || '{}'),
         ) as Record<string, unknown>;
         const rawEvidence = baseTraceEvidence(row as TraceGraphRow, call, persistedEvidence, contextual.evidence);
-        const effective = runtimeResolution(db, row as TraceGraphRow, rawEvidence, options.vars, workspaceIdForCall(db, String(call.id)), contextual.unresolvedReason);
+        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);
         const evidence = effective.evidence;
         const effectiveRow = effective.row;
         const targetNode = `${effectiveRow.to_kind}:${effectiveRow.to_id}`;
@@ -615,6 +613,8 @@ export function trace(
           confidence: Number(effectiveRow.confidence ?? call.confidence),
           unresolvedReason: effective.unresolvedReason,
         });
+        if ((options.dynamicMode ?? 'strict') === 'candidates')
+          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);

package/src/types.ts

@@ -199,6 +199,18 @@ export interface ImplementationHint {
   candidateFamily?: string;
   implementationRepo: string;
 }
+export type DynamicMode = 'strict' | 'candidates' | 'infer';
+export interface TraceOptions {
+  depth: number;
+  vars?: Record<string, string>;
+  includeExternal?: boolean;
+  includeDb?: boolean;
+  includeAsync?: boolean;
+  implementationRepo?: string;
+  implementationHints?: ImplementationHint[];
+  dynamicMode?: DynamicMode;
+  maxDynamicCandidates?: number;
+}
 export interface TraceEdge {
   step: number;
   type: string;