@saptools/service-flow 0.1.44 → 0.1.46

package/src/parsers/imported-wrapper-parser.ts

@@ -0,0 +1,262 @@
+import path from 'node:path';
+import ts from 'typescript';
+import { classifyODataPathIntent } from '../linker/odata-path-normalizer.js';
+import type { OutboundCallFact } from '../types.js';
+import { normalizePath } from '../utils/path-utils.js';
+import { importsFor, lineOf, readSource, type ImportBinding } from './service-binding-parser-helpers.js';
+
+interface WrapperSpec {
+  clientIndex: number;
+  pathIndex: number;
+  methodIndex?: number;
+  methodLiteral?: string;
+  sourceFile: string;
+  sourceLine: number;
+  chain: string[];
+}
+
+interface PathValue {
+  value?: string;
+  sourceKind: string;
+  rawExpression: string;
+}
+
+export async function parseImportedWrapperCalls(
+  repoPath: string,
+  filePath: string,
+  source: ts.SourceFile,
+  serviceBindings: Set<string>,
+): Promise<OutboundCallFact[]> {
+  const imports = await importsFor(repoPath, filePath, source);
+  const importedByLocal = new Map(imports.filter((item) => item.sourceFile).map((item) => [item.localName, item]));
+  const calls = collectImportedCalls(source, importedByLocal);
+  const out: OutboundCallFact[] = [];
+  const cache = new Map<string, Promise<WrapperSpec | undefined>>();
+  for (const call of calls) {
+    if (!ts.isIdentifier(call.expression)) continue;
+    const imported = importedByLocal.get(call.expression.text);
+    if (!imported?.sourceFile) continue;
+    const spec = await loadWrapperSpec(repoPath, imported, cache, 0);
+    const fact = spec ? wrapperCallFact(source, filePath, call, spec, serviceBindings) : undefined;
+    if (fact) out.push(fact);
+  }
+  return out;
+}
+
+function collectImportedCalls(source: ts.SourceFile, imports: Map<string, ImportBinding>): ts.CallExpression[] {
+  const calls: ts.CallExpression[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && imports.has(node.expression.text)) calls.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return calls;
+}
+
+async function loadWrapperSpec(
+  repoPath: string,
+  imported: ImportBinding,
+  cache: Map<string, Promise<WrapperSpec | undefined>>,
+  depth: number,
+): Promise<WrapperSpec | undefined> {
+  if (!imported.sourceFile || depth > 5) return undefined;
+  const key = `${imported.sourceFile}#${imported.exportedName}`;
+  const existing = cache.get(key);
+  if (existing) return existing;
+  const pending = inspectWrapper(repoPath, imported.sourceFile, imported.exportedName, cache, depth);
+  cache.set(key, pending);
+  return pending;
+}
+
+async function inspectWrapper(
+  repoPath: string,
+  sourceFile: string,
+  exportedName: string,
+  cache: Map<string, Promise<WrapperSpec | undefined>>,
+  depth: number,
+): Promise<WrapperSpec | undefined> {
+  const source = await readSource(path.join(repoPath, sourceFile));
+  if (!source) return undefined;
+  const named = findFunction(source, exportedName);
+  if (!named) return undefined;
+  const direct = directSendSpec(source, sourceFile, named.name, named.fn);
+  if (direct) return direct;
+  return nestedSendSpec(repoPath, sourceFile, source, named.name, named.fn, cache, depth);
+}
+
+function directSendSpec(source: ts.SourceFile, sourceFile: string, name: string, fn: ts.FunctionLikeDeclaration): WrapperSpec | undefined {
+  const params = parameterNames(fn);
+  const sends: ts.CallExpression[] = [];
+  visitFunctionBody(fn, (node) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'send') sends.push(node);
+  });
+  if (sends.length !== 1) return undefined;
+  const send = sends[0];
+  const receiver = send && ts.isPropertyAccessExpression(send.expression) && ts.isIdentifier(send.expression.expression) ? send.expression.expression.text : undefined;
+  const object = send?.arguments[0];
+  if (!receiver || !object || !ts.isObjectLiteralExpression(object)) return undefined;
+  const pathExpr = propertyExpression(object, 'path');
+  const methodExpr = propertyExpression(object, 'method');
+  const pathName = pathExpr && ts.isIdentifier(pathExpr) ? pathExpr.text : undefined;
+  const clientIndex = params.indexOf(receiver);
+  const pathIndex = pathName ? params.indexOf(pathName) : -1;
+  if (clientIndex < 0 || pathIndex < 0) return undefined;
+  const methodName = methodExpr && ts.isIdentifier(methodExpr) ? methodExpr.text : undefined;
+  const methodIndex = methodName ? params.indexOf(methodName) : -1;
+  return { clientIndex, pathIndex, methodIndex: methodIndex >= 0 ? methodIndex : undefined, methodLiteral: literal(methodExpr), sourceFile, sourceLine: lineOf(source, fn), chain: [name] };
+}
+
+async function nestedSendSpec(
+  repoPath: string,
+  sourceFile: string,
+  source: ts.SourceFile,
+  name: string,
+  fn: ts.FunctionLikeDeclaration,
+  cache: Map<string, Promise<WrapperSpec | undefined>>,
+  depth: number,
+): Promise<WrapperSpec | undefined> {
+  const imports = await importsFor(repoPath, sourceFile, source);
+  const byLocal = new Map(imports.filter((item) => item.sourceFile).map((item) => [item.localName, item]));
+  const calls: ts.CallExpression[] = [];
+  visitFunctionBody(fn, (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && byLocal.has(node.expression.text)) calls.push(node);
+  });
+  if (calls.length !== 1) return undefined;
+  const call = calls[0];
+  const imported = call && ts.isIdentifier(call.expression) ? byLocal.get(call.expression.text) : undefined;
+  const nested = imported ? await loadWrapperSpec(repoPath, imported, cache, depth + 1) : undefined;
+  if (!call || !nested) return undefined;
+  const params = parameterNames(fn);
+  const clientIndex = mappedParameterIndex(call.arguments[nested.clientIndex], params);
+  const pathIndex = mappedParameterIndex(call.arguments[nested.pathIndex], params);
+  if (clientIndex < 0 || pathIndex < 0) return undefined;
+  const methodIndex = nested.methodIndex === undefined ? undefined : mappedParameterIndex(call.arguments[nested.methodIndex], params);
+  return { clientIndex, pathIndex, methodIndex: methodIndex !== undefined && methodIndex >= 0 ? methodIndex : undefined, methodLiteral: nested.methodLiteral, sourceFile, sourceLine: lineOf(source, fn), chain: [name, ...nested.chain] };
+}
+
+function wrapperCallFact(
+  source: ts.SourceFile,
+  filePath: string,
+  call: ts.CallExpression,
+  spec: WrapperSpec,
+  serviceBindings: Set<string>,
+): OutboundCallFact | undefined {
+  const client = call.arguments[spec.clientIndex];
+  if (!client || !ts.isIdentifier(client) || !serviceBindings.has(client.text)) return undefined;
+  const pathValue = resolveCallerPath(call.arguments[spec.pathIndex], call);
+  const methodValue = spec.methodIndex === undefined ? spec.methodLiteral : literal(call.arguments[spec.methodIndex]);
+  const method = (methodValue ?? 'POST').toUpperCase();
+  const rawPath = pathValue.rawExpression;
+  const operationPathExpr = pathValue.value ? normalizeOperationPath(pathValue.value) : runtimePathExpression(rawPath);
+  return {
+    callType: 'remote_action',
+    serviceVariableName: client.text,
+    method,
+    operationPathExpr,
+    payloadSummary: call.getText(source),
+    sourceFile: normalizePath(filePath),
+    sourceLine: lineOf(source, call),
+    confidence: operationPathExpr ? 0.85 : 0.5,
+    unresolvedReason: pathValue.value ? undefined : 'dynamic_operation_path_identifier',
+    evidence: {
+      parser: 'typescript_ast',
+      classifier: pathValue.value ? 'imported_wrapper_literal_path' : 'imported_wrapper_dynamic_path',
+      receiver: client.text,
+      wrapperFunction: spec.chain[0],
+      wrapperChain: spec.chain,
+      callerSite: { sourceFile: normalizePath(filePath), sourceLine: lineOf(source, call) },
+      calleeSite: { sourceFile: spec.sourceFile, sourceLine: spec.sourceLine },
+      rawPathExpression: rawPath,
+      missingPathIdentifier: pathValue.value ? undefined : rawPath,
+      odataPathIntent: pathValue.value ? classifyODataPathIntent(operationPathExpr, method) : undefined,
+    },
+  };
+}
+
+function resolveCallerPath(expr: ts.Expression | undefined, use: ts.Node): PathValue {
+  if (!expr) return { sourceKind: 'missing', rawExpression: '' };
+  if (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) return { value: expr.text, sourceKind: 'literal', rawExpression: expr.getText() };
+  if (ts.isTemplateExpression(expr)) return { value: expr.getText().slice(1, -1), sourceKind: 'template', rawExpression: expr.getText() };
+  if (ts.isIdentifier(expr)) {
+    const initializer = constInitializer(expr.text, use);
+    if (initializer) {
+      const resolved = resolveCallerPath(initializer, initializer);
+      return { ...resolved, sourceKind: 'const', rawExpression: expr.text };
+    }
+  }
+  return { sourceKind: 'dynamic', rawExpression: expr.getText() };
+}
+
+function constInitializer(name: string, use: ts.Node): ts.Expression | undefined {
+  let found: ts.Expression | undefined;
+  const source = use.getSourceFile();
+  const visit = (node: ts.Node): void => {
+    if (node.getStart(source) >= use.getStart(source)) return;
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer && (node.parent.flags & ts.NodeFlags.Const) !== 0) found = node.initializer;
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return found;
+}
+
+function findFunction(source: ts.SourceFile, exportedName: string): { name: string; fn: ts.FunctionLikeDeclaration } | undefined {
+  const localName = exportedLocalName(source, exportedName);
+  for (const statement of source.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name?.text === localName) return { name: exportedName, fn: statement };
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === localName && declaration.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) return { name: exportedName, fn: declaration.initializer };
+    }
+  }
+  return undefined;
+}
+
+function exportedLocalName(source: ts.SourceFile, exportedName: string): string {
+  for (const statement of source.statements) {
+    if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue;
+    const match = statement.exportClause.elements.find((item) => item.name.text === exportedName);
+    if (match) return match.propertyName?.text ?? match.name.text;
+  }
+  return exportedName;
+}
+
+function visitFunctionBody(fn: ts.FunctionLikeDeclaration, visitor: (node: ts.Node) => void): void {
+  const visit = (node: ts.Node): void => {
+    if (node !== fn && ts.isFunctionLike(node)) return;
+    visitor(node);
+    ts.forEachChild(node, visit);
+  };
+  if (fn.body) visit(fn.body);
+}
+
+function parameterNames(fn: ts.FunctionLikeDeclaration): string[] {
+  return fn.parameters.map((parameter) => ts.isIdentifier(parameter.name) ? parameter.name.text : '');
+}
+
+function mappedParameterIndex(expr: ts.Expression | undefined, parameters: string[]): number {
+  return expr && ts.isIdentifier(expr) ? parameters.indexOf(expr.text) : -1;
+}
+
+function propertyExpression(object: ts.ObjectLiteralExpression, key: string): ts.Expression | undefined {
+  for (const property of object.properties) {
+    if (ts.isPropertyAssignment(property) && propertyName(property.name) === key) return property.initializer;
+    if (ts.isShorthandPropertyAssignment(property) && property.name.text === key) return property.name;
+  }
+  return undefined;
+}
+
+function propertyName(name: ts.PropertyName): string | undefined {
+  return ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? name.text : undefined;
+}
+
+function literal(expr: ts.Expression | undefined): string | undefined {
+  return expr && (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) ? expr.text : undefined;
+}
+
+function normalizeOperationPath(value: string): string {
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function runtimePathExpression(value: string): string | undefined {
+  return value ? `\${${value}}` : undefined;
+}

package/src/parsers/outbound-call-parser.ts

@@ -6,6 +6,8 @@ import type { OutboundCallFact } from '../types.js';
 import { normalizePath, stripQuotes } from '../utils/path-utils.js';
 import { summarizeExpression } from '../utils/redaction.js';
 import { classifyODataPathIntent } from '../linker/odata-path-normalizer.js';
+import { parseServiceBindings } from './service-binding-parser.js';
+import { parseImportedWrapperCalls } from './imported-wrapper-parser.js';
 function lineOf(text: string, idx: number): number {
   return text.slice(0, idx).split('\n').length;
 }
@@ -501,7 +503,9 @@ export async function parseOutboundCalls(
 ): Promise<OutboundCallFact[]> {
   const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');
   const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
-  return [...classifyOutboundCallsInSource(source, filePath).map((call) => call.fact), ...parseLocalServiceCalls(text, filePath)];
+  const bindingNames = new Set((await parseServiceBindings(repoPath, filePath)).map((binding) => binding.variableName));
+  const importedWrappers = await parseImportedWrapperCalls(repoPath, filePath, source, bindingNames);
+  return [...classifyOutboundCallsInSource(source, filePath).map((call) => call.fact), ...importedWrappers, ...parseLocalServiceCalls(text, filePath)];
 }
 function parseLocalServiceCalls(text: string, filePath: string): OutboundCallFact[] {
   const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, filePath.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);

package/src/parsers/symbol-parser.ts

@@ -42,7 +42,8 @@ function isObjectFunction(node: ts.Node): boolean {
 }
 type ParameterBinding =
   | { index: number; kind: 'identifier'; name: string }
-  | { index: number; kind: 'object_pattern'; properties: Array<{ property: string; local: string }> };
+  | { index: number; kind: 'object_pattern'; properties: Array<{ property: string; local: string }> }
+  | { index: number; kind: 'array_pattern'; elements: Array<{ index: number; local: string }> };
 type ParameterPropertyAlias = { parameter: string; property: string; local: string; kind: 'object_parameter_destructure'; line: number };
 const commonTerminalMembers = new Set(['push', 'includes', 'find', 'findIndex', 'map', 'filter', 'reduce', 'forEach', 'some', 'every', 'toUpperCase', 'toLowerCase', 'trim', 'split', 'join', 'get', 'set', 'has']);
 const loggerMembers = new Set(['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'log']);
@@ -99,6 +100,11 @@ function argumentEvidence(args: ts.NodeArray<ts.Expression>, source: ts.SourceFi
       }
       return { kind: 'object_literal', properties };
     }
+    if (ts.isArrayLiteralExpression(arg)) {
+      const elements = arg.elements.flatMap((element, index): Array<Record<string, unknown>> =>
+        ts.isIdentifier(element) ? [{ index, kind: 'identifier', name: element.text }] : []);
+      return { kind: 'array_literal', elements };
+    }
     return { kind: 'unsupported', expression: arg.getText(source) };
   });
 }
@@ -141,15 +147,24 @@ function parameterPropertyAliases(fn: ts.FunctionLikeDeclaration, source: ts.Sou
 function parameterBindings(params: ts.NodeArray<ts.ParameterDeclaration>): ParameterBinding[] {
   return params.flatMap((param, index): ParameterBinding[] => {
     if (ts.isIdentifier(param.name)) return [{ index, kind: 'identifier', name: param.name.text }];
-    if (!ts.isObjectBindingPattern(param.name)) return [];
-    const properties = param.name.elements.flatMap((element): Array<{ property: string; local: string }> => {
-      if (element.dotDotDotToken || ts.isObjectBindingPattern(element.name) || ts.isArrayBindingPattern(element.name)) return [];
-      const property = element.propertyName ? nameOf(element.propertyName) : nameOf(element.name);
-      if (!property) return [];
-      const local = bindingLocalName(element.name, element.initializer);
-      return local ? [{ property, local }] : [];
-    });
-    return properties.length > 0 ? [{ index, kind: 'object_pattern', properties }] : [];
+    if (ts.isObjectBindingPattern(param.name)) {
+      const properties = param.name.elements.flatMap((element): Array<{ property: string; local: string }> => {
+        if (element.dotDotDotToken || ts.isObjectBindingPattern(element.name) || ts.isArrayBindingPattern(element.name)) return [];
+        const property = element.propertyName ? nameOf(element.propertyName) : nameOf(element.name);
+        if (!property) return [];
+        const local = bindingLocalName(element.name, element.initializer);
+        return local ? [{ property, local }] : [];
+      });
+      return properties.length > 0 ? [{ index, kind: 'object_pattern', properties }] : [];
+    }
+    if (ts.isArrayBindingPattern(param.name)) {
+      const elements = param.name.elements.flatMap((element, elementIndex): Array<{ index: number; local: string }> =>
+        ts.isBindingElement(element) && !element.dotDotDotToken && ts.isIdentifier(element.name)
+          ? [{ index: elementIndex, local: element.name.text }]
+          : []);
+      return elements.length > 0 ? [{ index, kind: 'array_pattern', elements }] : [];
+    }
+    return [];
   });
 }
 export async function parseExecutableSymbols(repoPath: string, filePath: string): Promise<{ symbols: ExecutableSymbolFact[]; calls: SymbolCallFact[] }> {

package/src/trace/evidence.ts

@@ -1,5 +1,6 @@
 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';
 
 export interface TraceGraphRow extends Record<string, unknown> {
@@ -154,7 +155,11 @@ function withEffectiveResolution(
 
 function resolveRuntimeOperation(db: Db, evidence: Record<string, unknown>, workspaceId: number | undefined): ReturnType<typeof resolveOperation> {
   const servicePath = stringValue(evidence.servicePath);
-  const operationPath = stringValue(evidence.normalizedOperationPath ?? evidence.operationPath);
+  const rawOperationPath = stringValue(evidence.operationPath);
+  const normalized = normalizeODataOperationInvocationPath(rawOperationPath);
+  const operationPath = normalized?.wasInvocation
+    ? normalized.normalizedOperationPath
+    : stringValue(evidence.normalizedOperationPath) ?? rawOperationPath;
   const alias = stringValue(evidence.serviceAliasExpr ?? evidence.serviceAlias);
   const destination = stringValue(evidence.destination);
   return resolveOperation(db, { servicePath, operationPath, alias, destination, hasExplicitOverride: true, isDynamic: true }, workspaceId);

package/src/trace/implementation-hints.ts

@@ -0,0 +1,223 @@
+import type { ImplementationHint } from '../types.js';
+
+interface Candidate {
+  accepted?: boolean;
+  methodId?: number;
+  sourceFile?: string;
+  handlerPackage?: { name?: string; packageName?: string };
+  modelPackage?: { name?: string; packageName?: string };
+  servicePath?: string;
+  operationPath?: string;
+}
+
+interface EdgeEvidence {
+  servicePath?: string;
+  operationPath?: string;
+  ambiguityReasons?: string[];
+  candidateFamilies?: Array<{ packageName?: string }>;
+  candidates?: Candidate[];
+  modelPackage?: { name?: string; packageName?: string };
+}
+
+export interface ImplementationSelection {
+  methodId?: string;
+  blocksAutomatic: boolean;
+  evidence: Record<string, unknown>;
+}
+
+export function parseImplementationHint(value: string): ImplementationHint {
+  const hint: Partial<ImplementationHint> = {};
+  for (const part of value.split(',')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0 || separator === part.length - 1) throw new Error(`Invalid implementation hint field: ${part}`);
+    assignHintField(hint, part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+  }
+  if (!hint.implementationRepo) throw new Error('Scoped implementation hint requires an implementation repo selection');
+  return { ...hint, implementationRepo: hint.implementationRepo };
+}
+
+export function selectImplementation(
+  rawEvidence: Record<string, unknown>,
+  hints: ImplementationHint[] | undefined,
+  legacyRepo: string | undefined,
+): ImplementationSelection {
+  const evidence = asEvidence(rawEvidence);
+  const scoped = hints ?? [];
+  const matchingHints = scoped.filter((hint) => hintMatchesEdge(hint, evidence));
+  if (matchingHints.length === 0) {
+    if (legacyRepo) return selectCandidate(evidence, legacyHint(legacyRepo), 'implementation_repo_hint');
+    const reason = scoped.length > 0 ? 'no_scoped_hint_matched_edge' : 'no_implementation_hint_supplied';
+    return { blocksAutomatic: false, evidence: { status: 'not_matched', reason, strategy: 'scoped_implementation_hint' } };
+  }
+  if (matchingHints.length > 1) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: 'tied',
+        reason: 'multiple_scoped_hints_matched_edge',
+        strategy: 'scoped_implementation_hint',
+        matchedHints: matchingHints,
+        candidateCount: matchingHints.length,
+      },
+    };
+  }
+  const hint = matchingHints[0];
+  return hint ? selectCandidate(evidence, hint, 'scoped_implementation_hint') : { blocksAutomatic: false, evidence: { status: 'not_matched' } };
+}
+
+export function implementationHintDiagnostic(
+  selection: ImplementationSelection,
+  suggestions?: unknown,
+): Record<string, unknown> | undefined {
+  if (!selection.blocksAutomatic || selection.methodId) return undefined;
+  return {
+    severity: 'warning',
+    code: 'implementation_hint_mismatch',
+    message: 'Implementation hint did not select exactly one viable candidate',
+    hintStatus: selection.evidence.status,
+    candidateCount: selection.evidence.candidateCount,
+    implementationHintSuggestions: Array.isArray(suggestions) && suggestions.length > 0 ? suggestions : undefined,
+    implementationSelection: selection.evidence,
+  };
+}
+
+export function implementationHintSuggestions(rawEvidence: Record<string, unknown>): Array<Record<string, unknown>> {
+  const evidence = asEvidence(rawEvidence);
+  const accepted = (evidence.candidates ?? []).filter((candidate) => candidate.accepted);
+  if (accepted.length < 2) return [];
+  const repos = selectableRepositories(accepted);
+  return accepted
+    .flatMap((candidate) => {
+      const repo = candidate.handlerPackage?.name;
+      if (!repo || !repos.includes(repo)) return [];
+      const hint = suggestionHint(evidence, candidate, repo);
+      return [{
+        servicePath: hint.servicePath,
+        operationPath: hint.operationPath,
+        ambiguityReason: evidence.ambiguityReasons?.[0],
+        candidateFamily: hint.candidateFamily,
+        selectableImplementationRepositories: repos,
+        implementationRepo: repo,
+        hint,
+        cli: `--implementation-hint ${hintString(hint)}`,
+      }];
+    });
+}
+
+function selectableRepositories(candidates: Candidate[]): string[] {
+  const repos = new Set(candidates.flatMap((candidate) => candidate.handlerPackage?.name ? [candidate.handlerPackage.name] : []));
+  return [...repos]
+    .filter((repo) => candidates.filter((candidate) => candidateMatchesRepo(candidate, repo)).length === 1)
+    .sort();
+}
+
+function assignHintField(hint: Partial<ImplementationHint>, key: string, value: string): void {
+  if (key === 'service' || key === 'servicePath') hint.servicePath = value;
+  else if (key === 'operation' || key === 'operationPath') hint.operationPath = value;
+  else if (key === 'package' || key === 'packageName') hint.packageName = value;
+  else if (key === 'repository' || key === 'repositoryName') hint.repositoryName = value;
+  else if (key === 'family' || key === 'candidateFamily') hint.candidateFamily = value;
+  else if (key === 'repo' || key === 'implementationRepo' || key === 'select') hint.implementationRepo = value;
+  else throw new Error(`Unknown implementation hint field: ${key}`);
+}
+
+function selectCandidate(evidence: EdgeEvidence, hint: ImplementationHint, strategy: string): ImplementationSelection {
+  const matches = (evidence.candidates ?? []).filter((candidate) =>
+    candidate.accepted && candidateMatchesRepo(candidate, hint.implementationRepo));
+  const selected = matches.length === 1 ? matches[0] : undefined;
+  if (!selected || selected.methodId === undefined) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: matches.length > 1 ? 'tied' : 'not_matched',
+        reason: matches.length > 1 ? 'hint_matched_multiple_candidates' : 'hint_matched_zero_candidates',
+        strategy,
+        matchedHint: hint,
+        selectedRepo: hint.implementationRepo,
+        candidateCount: matches.length,
+      },
+    };
+  }
+  return {
+    methodId: String(selected.methodId),
+    blocksAutomatic: false,
+    evidence: {
+      status: 'selected',
+      guided: true,
+      strategy,
+      matchedHint: hint,
+      selectedRepo: hint.implementationRepo,
+      selectedMethodId: selected.methodId,
+      ambiguityReason: evidence.ambiguityReasons?.[0],
+    },
+  };
+}
+
+function suggestionHint(evidence: EdgeEvidence, candidate: Candidate, repo: string): ImplementationHint {
+  const servicePath = evidence.servicePath ?? candidate.servicePath;
+  const operationPath = evidence.operationPath ?? candidate.operationPath;
+  const family = usefulCandidateFamily(evidence, candidate);
+  return {
+    ...(servicePath ? { servicePath } : {}),
+    ...(operationPath ? { operationPath } : {}),
+    ...(evidence.modelPackage?.packageName ? { packageName: evidence.modelPackage.packageName } : {}),
+    ...(evidence.modelPackage?.name ? { repositoryName: evidence.modelPackage.name } : {}),
+    ...(family ? { candidateFamily: family } : {}),
+    implementationRepo: repo,
+  };
+}
+
+function usefulCandidateFamily(evidence: EdgeEvidence, candidate: Candidate): string | undefined {
+  const family = candidate.handlerPackage?.packageName;
+  if (!family) return undefined;
+  if ((evidence.candidateFamilies ?? []).some((item) => item.packageName === family)) return family;
+  const acceptedFamilies = new Set(
+    (evidence.candidates ?? [])
+      .filter((item) => item.accepted)
+      .flatMap((item) => item.handlerPackage?.packageName ? [item.handlerPackage.packageName] : []),
+  );
+  return acceptedFamilies.size > 1 ? family : undefined;
+}
+
+function hintString(hint: ImplementationHint): string {
+  const fields = [
+    ['service', hint.servicePath],
+    ['operation', hint.operationPath],
+    ['package', hint.packageName],
+    ['repository', hint.repositoryName],
+    ['family', hint.candidateFamily],
+    ['repo', hint.implementationRepo],
+  ];
+  return fields.flatMap(([key, value]) => value ? [`${key}=${value}`] : []).join(',');
+}
+
+function hintMatchesEdge(hint: ImplementationHint, evidence: EdgeEvidence): boolean {
+  const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
+  const familyNames = new Set([
+    ...(evidence.candidateFamilies ?? []).flatMap((family) => family.packageName ? [family.packageName] : []),
+    ...(evidence.candidates ?? []).flatMap((candidate) => candidate.handlerPackage?.packageName ? [candidate.handlerPackage.packageName] : []),
+  ]);
+  return matches(hint.servicePath, evidence.servicePath ?? evidence.candidates?.[0]?.servicePath)
+    && matches(hint.operationPath, evidence.operationPath ?? evidence.candidates?.[0]?.operationPath)
+    && matches(hint.packageName, model?.packageName)
+    && matches(hint.repositoryName, model?.name)
+    && (!hint.candidateFamily || familyNames.has(hint.candidateFamily));
+}
+
+function candidateMatchesRepo(candidate: Candidate, value: string): boolean {
+  return candidate.handlerPackage?.name === value
+    || candidate.handlerPackage?.packageName === value
+    || candidate.sourceFile?.startsWith(value) === true;
+}
+
+function matches(expected: string | undefined, actual: string | undefined): boolean {
+  return expected === undefined || expected === actual;
+}
+
+function legacyHint(implementationRepo: string): ImplementationHint {
+  return { implementationRepo };
+}
+
+function asEvidence(value: Record<string, unknown>): EdgeEvidence {
+  return value as EdgeEvidence;
+}