@saptools/service-flow 0.1.30 → 0.1.31

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.31
+
+- Resolve operation and path trace selectors from indexed CDS operations and persisted implementation edges before conservative handler fallback, including generated `Action<Name>` and `Func<Name>` decorator constants whose method names differ from public operation names.
+- Emit the selected start operation and initial implementation hop once, with structured start-resolution evidence and ambiguity/not-found diagnostics that point to the operation, implementation edge, or handler-scope stage.
+- Replace numeric external HTTP terminal targets with semantic external destination and endpoint nodes, preserving redacted structured target evidence for destinations, static URLs, dynamic URL expressions, and unknown calls.
+- Add schema version 6 migration columns for queryable external target metadata and a strict doctor aggregate for external HTTP target quality.
+
 ## 0.1.30
 
 - Normalize balanced OData operation invocations when multiline template placeholders appear inside function/action argument lists.

package/README.md

@@ -219,7 +219,15 @@ service-flow list calls --workspace /path/to/workspace --repo facade-service --o
 | `list operations` | Print indexed actions/functions/events, optionally filtered by repo and service |
 | `list calls` | Print indexed outbound calls, optionally filtered by repo and operation/path |
 
-### Troubleshooting resolution accuracy
+### Operation selector resolution
+
+Operation-based trace starts first resolve indexed CDS operations, then follow the persisted `OPERATION_IMPLEMENTED_BY_HANDLER` graph edge to the exact handler method symbol. Generated decorator constants such as `ActionPublishRecord.name` and `FuncLookupRecord.name` are normalized through the same shared helper used by linking and diagnostics, so public operations like `/publishRecord` can trace into methods such as `executePublish`. If the same operation name exists in multiple services or repositories, `service-flow` returns `trace_start_ambiguous`; add `--service /CatalogService` or `--repo catalog-api` to disambiguate. Unique operation selectors emit the initial operation node and implementation hop exactly once before traversing handler-owned calls.
+
+### External HTTP targets
+
+External HTTP facts use semantic terminal nodes instead of outbound-call row ids. Literal destinations render as `External destination: ANALYTICS_API`; static absolute or relative URLs render as redacted `External endpoint` labels; dynamic URL expressions render as `External endpoint: dynamic URL`; unavailable target evidence renders as `External endpoint: unknown`. URL user information, query-string values, credentials, tokens, cookies, headers, and payload bodies are not stored in labels. Run `service-flow link` after schema migration so legacy numeric targets are rebuilt from the current parser evidence. `service-flow doctor --strict` reports `strict_external_http_target_quality` with semantic, dynamic, unknown, numeric, and malformed-evidence counts.
+
+## Troubleshooting resolution accuracy
 
 - If a remote edge is unresolved, run `service-flow list calls --operation <name>`
   and `service-flow inspect operation <name>` to compare the captured call path

package/TECHNICAL-NOTE.md

@@ -1,5 +1,12 @@
 # Service Flow Resolution Notes
 
+
+## 0.1.31 selector and external target notes
+
+Operation trace selectors are resolved from CDS operation facts before handler-source fallback. The start resolver scopes by repository and service path, requires disambiguation when multiple repositories or services match, and only queues traversal from a resolved implementation edge. Generated operation decorator constants are normalized in `operation-decorator-normalizer` so linker, trace fallback, diagnostics, and tests share one conservative implementation.
+
+Schema version 6 adds queryable external target metadata columns to `outbound_calls`. The linker writes semantic `external_destination` or `external_endpoint` graph targets and keeps redacted structured target details in edge evidence. Existing databases migrate forward without dropping facts; relinking rebuilds legacy numeric external HTTP targets.
+
 ## 0.1.30 OData invocation argument placeholder notes
 
 - Balanced top-level OData function/action imports such as `/readDetails(ID='${id}',version=0)` now normalize to the operation segment even when placeholder expressions span multiple lines or contain nested JavaScript parentheses.

package/dist/{chunk-UHYHSYCS.js → chunk-AM2JZFQ6.js}

@@ -798,6 +798,70 @@ function nameOfProperty(name) {
   if (ts4.isIdentifier(name) || ts4.isStringLiteral(name) || ts4.isNumericLiteral(name)) return name.text;
   return void 0;
 }
+function staticExpressionText(expr, initializers) {
+  if (!expr) return void 0;
+  if (isStringLike(expr)) return expr.text;
+  if (ts4.isIdentifier(expr) && initializers.has(expr.text)) return staticExpressionText(initializers.get(expr.text), initializers);
+  return void 0;
+}
+function propertyInitializer(object, key) {
+  for (const property of object.properties) {
+    if (ts4.isPropertyAssignment(property) && nameOfProperty(property.name) === key) return property.initializer;
+    if (ts4.isShorthandPropertyAssignment(property) && property.name.text === key) return property.name;
+  }
+  return void 0;
+}
+function httpMethodFromObject(object, initializers) {
+  const text = staticExpressionText(propertyInitializer(object, "method"), initializers);
+  return text ? stripQuotes(text).toUpperCase() : void 0;
+}
+function urlTargetFromExpression(expr, initializers) {
+  const text = staticExpressionText(expr, initializers);
+  if (text) return { kind: "static_url", expression: text, dynamic: false };
+  if (expr && (ts4.isTemplateExpression(expr) || ts4.isIdentifier(expr) || ts4.isPropertyAccessExpression(expr) || ts4.isCallExpression(expr))) return { kind: "url_expression", expression: expr.getText(expr.getSourceFile()), dynamic: true };
+  return { kind: "unknown", dynamic: false };
+}
+function destinationTargetFromExpression(expr, initializers) {
+  const text = staticExpressionText(expr, initializers);
+  if (text) return { kind: "destination", expression: text, dynamic: false };
+  if (expr && ts4.isIdentifier(expr)) return { kind: "destination", expression: expr.text, dynamic: true };
+  return void 0;
+}
+function externalHttpEvidence(node, source, initializers) {
+  const expr = node.expression;
+  const exprText = expr.getText(source);
+  if (exprText === "useOrFetchDestination") {
+    const objectArg = node.arguments[0];
+    if (objectArg && ts4.isObjectLiteralExpression(objectArg)) {
+      const destination = destinationTargetFromExpression(propertyInitializer(objectArg, "destinationName"), initializers);
+      return { externalTarget: destination ?? { kind: "unknown", dynamic: false }, classifier: "sap_destination_lookup", sourceCallShape: "useOrFetchDestination" };
+    }
+  }
+  if (exprText === "executeHttpRequest") {
+    const destination = destinationTargetFromExpression(node.arguments[0], initializers);
+    const config = node.arguments[1];
+    const method = config && ts4.isObjectLiteralExpression(config) ? httpMethodFromObject(config, initializers) : void 0;
+    const url = config && ts4.isObjectLiteralExpression(config) ? urlTargetFromExpression(propertyInitializer(config, "url"), initializers) : { kind: "unknown", dynamic: false };
+    return { method, externalTarget: destination ? { ...url, destination } : url, classifier: "sap_execute_http_request", sourceCallShape: "executeHttpRequest" };
+  }
+  if (exprText === "axios") {
+    const config = node.arguments[0];
+    if (config && ts4.isObjectLiteralExpression(config)) {
+      const method = httpMethodFromObject(config, initializers);
+      return { method, externalTarget: urlTargetFromExpression(propertyInitializer(config, "url"), initializers), classifier: "axios_config_call", sourceCallShape: "axios(config)" };
+    }
+    return { externalTarget: { kind: "unknown", dynamic: false }, classifier: "axios_unknown_call", sourceCallShape: "axios(...)" };
+  }
+  if (exprText === "fetch") {
+    const init = node.arguments[1];
+    const method = init && ts4.isObjectLiteralExpression(init) ? httpMethodFromObject(init, initializers) : void 0;
+    return { method, externalTarget: urlTargetFromExpression(node.arguments[0], initializers), classifier: "fetch_call", sourceCallShape: "fetch" };
+  }
+  if (ts4.isPropertyAccessExpression(expr) && ["get", "post", "put", "patch", "delete", "head"].includes(expr.name.text) && expr.expression.getText(source) === "axios") {
+    return { method: expr.name.text.toUpperCase(), externalTarget: urlTargetFromExpression(node.arguments[0], initializers), classifier: "axios_member_call", sourceCallShape: `axios.${expr.name.text}` };
+  }
+  return void 0;
+}
 function collectServiceVariables(source) {
   const vars = /* @__PURE__ */ new Set(["cds", "messaging", "messageClient", "eventClient"]);
   const visit = (node) => {
@@ -930,8 +994,9 @@ function classifyOutboundCallsInSource(source, filePath) {
           const eventName = literalText(node.arguments[0]);
           if (eventName) add(node, { callType: expr.name.text === "on" ? "async_subscribe" : "async_emit", serviceVariableName: rootReceiver ?? receiver, eventNameExpr: eventName }, { receiver, rootReceiver, classifier: expr.name.text === "on" ? "cap_service_event_subscription" : "cap_service_event_emit", receiverClassification: "cap_evidence" });
         }
-      } else if (exprText === "axios" || exprText === "executeHttpRequest" || exprText === "useOrFetchDestination") {
-        add(node, { callType: "external_http", payloadSummary: summarizeExpression(node.arguments.map((arg) => arg.getText(source)).join(", ")), confidence: 0.7, unresolvedReason: "External HTTP destination is outside indexed CAP services" });
+      } else {
+        const external = externalHttpEvidence(node, source, initializers);
+        if (external) add(node, { callType: "external_http", method: external.method, payloadSummary: summarizeExpression(node.arguments.map((arg) => arg.getText(source)).join(", ")), confidence: 0.7, unresolvedReason: "External HTTP destination is outside indexed CAP services" }, { classifier: external.classifier, externalTarget: { ...external.externalTarget, method: external.method, parserClassifier: external.classifier, sourceCallShape: external.sourceCallShape }, sourceCallShape: external.sourceCallShape });
       }
     }
     ts4.forEachChild(node, visit);
@@ -1861,6 +1926,80 @@ function linkHelperPackages(db, workspaceId, generation) {
   return summary;
 }
 
+// src/linker/operation-decorator-normalizer.ts
+function lowerFirst(value) {
+  return value ? `${value[0]?.toLowerCase() ?? ""}${value.slice(1)}` : value;
+}
+function normalizedOperationName(value) {
+  return value.replace(/^\//, "");
+}
+function clean(value) {
+  return value.replace(/^[`'"]|[`'"]$/g, "");
+}
+function generatedFromConstantName(value) {
+  for (const prefix of ["Action", "Func"]) {
+    if (value.startsWith(prefix) && value.length > prefix.length && /^[A-Z]/.test(value.slice(prefix.length))) return lowerFirst(value.slice(prefix.length));
+  }
+  return void 0;
+}
+function normalizeDecoratorOperation(value, raw) {
+  if (value) {
+    const literal = clean(value);
+    const generated = generatedFromConstantName(literal);
+    return generated ?? normalizedOperationName(literal);
+  }
+  if (!raw) return void 0;
+  const expression = raw.trim();
+  const nameMatch = /(?:^|\.)(Action[A-Z][\w$]*|Func[A-Z][\w$]*)\.name$/.exec(expression);
+  if (nameMatch?.[1]) return generatedFromConstantName(nameMatch[1]);
+  const tail = expression.split(".").filter(Boolean).at(-1);
+  return tail ? normalizedOperationName(clean(tail)) : void 0;
+}
+
+// src/linker/external-http-target.ts
+import { createHash } from "crypto";
+var sensitiveKeys = /* @__PURE__ */ new Set(["token", "access_token", "id_token", "api_key", "apikey", "key", "password", "passwd", "pwd", "secret", "client_secret", "authorization", "cookie", "signature"]);
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+function methodPrefix(method) {
+  return typeof method === "string" && method.length > 0 ? `${method.toUpperCase()} ` : "";
+}
+function redactUrl(value) {
+  try {
+    const url = new URL(value, value.startsWith("/") ? "https://relative.invalid" : void 0);
+    url.username = "";
+    url.password = "";
+    for (const key of [...url.searchParams.keys()]) url.searchParams.set(key, sensitiveKeys.has(key.toLowerCase()) ? "<redacted>" : "<redacted>");
+    const path9 = `${url.pathname}${url.search ? url.search : ""}`;
+    return value.startsWith("/") ? path9 : `${url.origin}${path9}`;
+  } catch {
+    return value.replace(/([?&][^=;&]*(?:token|key|password|secret|cookie|authorization)[^=;&]*=)[^&]*/gi, "$1<redacted>");
+  }
+}
+function externalHttpTarget(call) {
+  const evidence = typeof call.evidence_json === "string" ? safeParse(call.evidence_json) : {};
+  const target = evidence.externalTarget && typeof evidence.externalTarget === "object" && !Array.isArray(evidence.externalTarget) ? evidence.externalTarget : {};
+  const method = typeof call.method === "string" ? call.method : typeof target.method === "string" ? target.method : void 0;
+  const kind = typeof target.kind === "string" ? target.kind : "unknown";
+  const expression = typeof target.expression === "string" ? target.expression : void 0;
+  if (kind === "destination" && expression) return { kind, toKind: "external_destination", toId: `destination:${expression}`, label: `External destination: ${expression}`, method, dynamic: false, expression };
+  if (kind === "static_url" && expression) {
+    const redacted = redactUrl(expression);
+    return { kind, toKind: "external_endpoint", toId: `endpoint:${hash(`${method ?? ""}:${redacted}`)}`, label: `External endpoint: ${methodPrefix(method)}${redacted}`, method, dynamic: false, expression: redacted };
+  }
+  if (kind === "url_expression" && expression) return { kind, toKind: "external_endpoint", toId: `dynamic:${hash(expression)}`, label: `External endpoint: ${methodPrefix(method)}dynamic URL`, method, dynamic: true, expression: `expr:${hash(expression)}` };
+  return { kind: "unknown", toKind: "external_endpoint", toId: "unknown", label: "External endpoint: unknown", method, dynamic: false };
+}
+function safeParse(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
 // src/linker/cross-repo-linker.ts
 function linkWorkspace(db, workspaceId, vars = {}) {
   return db.transaction(() => {
@@ -1930,10 +2069,12 @@ function insertCallEdge(db, workspaceId, call, vars, generation) {
   const edgeType = callType === "local_db_query" ? "HANDLER_RUNS_DB_QUERY" : callType === "external_http" ? "HANDLER_CALLS_EXTERNAL_HTTP" : callType === "async_emit" ? "HANDLER_EMITS_EVENT" : callType === "async_subscribe" ? "EVENT_CONSUMED_BY_HANDLER" : resolution.status === "dynamic" ? "DYNAMIC_EDGE_CANDIDATE" : "UNRESOLVED_EDGE";
   const status = edgeType === "DYNAMIC_EDGE_CANDIDATE" ? "dynamic" : resolution.status === "ambiguous" ? "ambiguous" : edgeType === "UNRESOLVED_EDGE" ? "unresolved" : "terminal";
   const unresolvedReason = status === "terminal" ? null : String(call.unresolved_reason ?? unresolvedOperationReason(resolution));
-  const targetKind = callType === "local_db_query" ? "db_entity" : callType.startsWith("async_") ? "event" : "external";
-  const targetId = callType === "local_db_query" ? String(call.query_entity ?? "unknown") : callType === "remote_action" ? op ? `Remote action: ${op}` : call.unresolved_reason === "dynamic_operation_path_identifier" ? "Remote action: dynamic path" : "Remote action: unknown path" : String(call.event_name_expr ?? op ?? call.id);
+  const externalTarget = callType === "external_http" ? externalHttpTarget(call) : void 0;
+  const targetKind = callType === "local_db_query" ? "db_entity" : callType.startsWith("async_") ? "event" : externalTarget?.toKind ?? "external_endpoint";
+  const targetId = callType === "local_db_query" ? String(call.query_entity ?? "unknown") : callType === "remote_action" ? op ? `Remote action: ${op}` : call.unresolved_reason === "dynamic_operation_path_identifier" ? "Remote action: dynamic path" : "Remote action: unknown path" : callType === "external_http" ? String(externalTarget?.toId ?? "unknown") : String(call.event_name_expr ?? op ?? "unknown");
   const graphLevelDynamic = edgeType === "DYNAMIC_EDGE_CANDIDATE" && resolution.status === "dynamic";
-  db.prepare("INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)").run(workspaceId, edgeType, status, "call", String(call.id), targetKind, targetId, Number(call.confidence ?? 0.2), JSON.stringify(evidence), graphLevelDynamic ? 1 : 0, unresolvedReason, generation);
+  const finalEvidence = externalTarget ? { ...evidence, externalTarget } : evidence;
+  db.prepare("INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)").run(workspaceId, edgeType, status, "call", String(call.id), targetKind, targetId, Number(call.confidence ?? 0.2), JSON.stringify(finalEvidence), graphLevelDynamic ? 1 : 0, unresolvedReason, generation);
   return { status, callType };
 }
 function unresolvedOperationReason(resolution) {
@@ -2187,28 +2328,16 @@ function candidateEvidence(candidate, rank) {
   };
 }
 function implementationMethodSignal(row, operation) {
-  const op = normalizedOperation(String(operation.operationPath ?? operation.operationName ?? ""));
+  const op = normalizedOperationName(String(operation.operationPath ?? operation.operationName ?? ""));
   const decorator = normalizeDecoratorOperation(typeof row.decoratorValue === "string" ? row.decoratorValue : void 0, typeof row.decoratorRawExpression === "string" ? row.decoratorRawExpression : void 0);
   if (decorator && decorator === op) return { matches: true, contradicted: false, acceptedReasons: ["decorator targets operation"], rejectedReasons: [] };
   if (decorator && decorator !== op) return { matches: false, contradicted: true, acceptedReasons: [], rejectedReasons: ["method_name_matches_but_decorator_targets_different_operation"] };
   if (String(row.methodName ?? "") === op) return { matches: true, contradicted: false, acceptedReasons: ["method name fallback matched operation"], rejectedReasons: [] };
   return { matches: false, contradicted: false, acceptedReasons: [], rejectedReasons: ["method name does not match operation"] };
 }
-function normalizeDecoratorOperation(value, raw) {
-  const candidate = value ?? raw?.split(".").filter(Boolean).at(-2);
-  if (!candidate) return void 0;
-  const cleaned = candidate.replace(/^['"`]|['"`]$/g, "");
-  for (const prefix of ["Func", "Action"]) {
-    if (cleaned.startsWith(prefix) && cleaned.length > prefix.length) return lowerFirst(cleaned.slice(prefix.length));
-  }
-  return normalizedOperation(cleaned);
-}
 function upperFirst(value) {
   return value ? `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}` : value;
 }
-function lowerFirst(value) {
-  return value ? `${value[0]?.toLowerCase() ?? ""}${value.slice(1)}` : value;
-}
 function flag(value) {
   return Boolean(Number(value ?? 0));
 }
@@ -2227,6 +2356,25 @@ function normalizeOperation(value) {
 function positiveDepth(value) {
   return Number.isFinite(value) && value > 0 ? Math.floor(value) : 25;
 }
+function operationStartScope(db, repoId, start) {
+  const requested = normalizeOperation(start.operationPath ?? start.operation);
+  if (!requested) return void 0;
+  const rows2 = db.prepare(`SELECT o.id operationId,o.operation_name operationName,o.operation_path operationPath,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}`);
+  if (rows2.length === 0) return { diagnostics: [{ severity: "warning", code: "trace_start_not_found", message: "No indexed operation matched the requested trace selector", normalizedSelectorValue: requested }] };
+  const repoCount = new Set(rows2.map((row) => String(row.repoName))).size;
+  const serviceCount = new Set(rows2.map((row) => `${String(row.repoName)}:${String(row.servicePath)}`)).size;
+  if (!repoId && repoCount > 1) return { diagnostics: [{ severity: "warning", code: "trace_start_ambiguous", message: "Operation trace start matched multiple repositories; add --repo to disambiguate", normalizedSelectorValue: requested, candidates: rows2 }] };
+  if (!start.servicePath && serviceCount > 1) return { diagnostics: [{ severity: "warning", code: "trace_start_ambiguous", message: "Operation trace start matched multiple services; add --service to disambiguate", normalizedSelectorValue: requested, candidates: rows2 }] };
+  if (rows2.length !== 1) return { diagnostics: [{ severity: "warning", code: "trace_start_ambiguous", message: "Operation trace start matched multiple indexed operations", normalizedSelectorValue: requested, candidates: rows2 }] };
+  const operationId = String(rows2[0]?.operationId);
+  const impl = implementationScope(db, operationId);
+  if (impl.edge?.status === "resolved" && impl.files.size > 0) return { files: impl.files, symbols: impl.symbolId ? /* @__PURE__ */ new Set([impl.symbolId]) : void 0, operationId, diagnostics: [] };
+  if (impl.edge) return { operationId, diagnostics: [{ severity: "warning", code: impl.edge.status === "ambiguous" ? "trace_start_ambiguous" : "trace_start_not_found", message: `Indexed operation matched but implementation edge is ${String(impl.edge.status ?? "unresolved")}`, implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, candidates: parseEvidence(impl.edge.evidence_json).candidates }] };
+  return { operationId, diagnostics: [{ severity: "warning", code: "trace_start_not_found", message: "Indexed operation matched but no implementation candidate exists" }] };
+}
 function sourceFilesForStart(db, repoId, start) {
   const handler = start.handler;
   const operation = normalizeOperation(start.operation ?? start.operationPath);
@@ -2272,7 +2420,8 @@ function startScope(db, start) {
     "SELECT id,name FROM repositories WHERE name=? OR package_name=?"
   ).get(start.repo, start.repo) : void 0;
   if (start.repo && !repo) return { repo, selectorMatched: false };
-  const sourceScope = sourceFilesForStart(db, repo?.id, start);
+  const operationScope = operationStartScope(db, repo?.id, start);
+  const sourceScope = operationScope?.files ? operationScope : sourceFilesForStart(db, repo?.id, start);
   const sourceFiles = sourceScope?.files;
   const hasSelector = Boolean(
     start.handler ?? start.operation ?? start.operationPath ?? start.servicePath
@@ -2283,7 +2432,9 @@ function startScope(db, start) {
     repo,
     sourceFiles,
     symbolIds: sourceScope?.symbols,
-    selectorMatched: !hasSelector || sourceFiles !== void 0
+    selectorMatched: !hasSelector || sourceFiles !== void 0,
+    startOperationId: operationScope?.operationId,
+    startDiagnostics: operationScope?.diagnostics
   };
 }
 function handlerFilesForOperation(db, operationId) {
@@ -2530,6 +2681,10 @@ function edgeTarget(row, evidence) {
   const targetRepo = typeof evidence.targetRepo === "string" ? evidence.targetRepo : "";
   if (row.edge_type === "HANDLER_RUNS_DB_QUERY") return `Entity: ${row.to_id || "unknown"}`;
   if (row.edge_type === "HANDLER_RUNS_REMOTE_QUERY") return typeof evidence.remoteQueryTarget === "string" ? evidence.remoteQueryTarget : `Remote query: ${row.to_id || "unknown"}`;
+  if (row.edge_type === "HANDLER_CALLS_EXTERNAL_HTTP") {
+    const target = evidence.externalTarget;
+    return typeof target?.label === "string" ? target.label : `External endpoint: ${row.to_id || "unknown"}`;
+  }
   return servicePath && operationPath ? `${servicePath}${operationPath}` : targetOperation ? `${targetRepo}:${targetOperation}` : row.to_id;
 }
 function trace(db, start, options) {
@@ -2540,7 +2695,8 @@ function trace(db, start, options) {
   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);
   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.` });
-  if (!scope.selectorMatched)
+  for (const diagnostic of scope.startDiagnostics ?? []) diagnostics.unshift(diagnostic);
+  if (!scope.selectorMatched && !scope.startDiagnostics?.length)
     diagnostics.unshift({
       severity: "warning",
       code: "trace_start_not_found",
@@ -2549,27 +2705,21 @@ function trace(db, start, options) {
   const maxDepth = positiveDepth(options.depth);
   const edges = [];
   const nodes = /* @__PURE__ */ new Map();
+  const seenEdges = /* @__PURE__ */ new Set();
   const queue = scope.selectorMatched ? [{ repoId: scope.repo?.id, files: scope.sourceFiles, symbolIds: scope.symbolIds, depth: 1, context: /* @__PURE__ */ new Map() }] : [];
-  if (start.servicePath && (start.operation ?? start.operationPath)) {
-    const startOperation = normalizeOperation(start.operation ?? start.operationPath);
-    const startRows = db.prepare(`SELECT o.id operationId,r.name repoName,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 s.repo_id=?) AND s.service_path=? AND (o.operation_path=? OR o.operation_name=?) ORDER BY r.name,o.id LIMIT 2`).all(scope.repo?.id, scope.repo?.id, start.servicePath, startOperation, startOperation);
-    if (!scope.repo && startRows.length > 1) diagnostics.unshift({ severity: "warning", code: "trace_start_ambiguous", message: "Service/path trace start matched multiple repositories; add --repo to disambiguate", candidates: startRows });
-    const row = startRows.length === 1 ? startRows[0] : void 0;
-    if (row?.operationId !== void 0) {
-      const opId = String(row.operationId);
-      const op = operationNode(db, opId);
-      const impl = implementationScope(db, opId);
-      if (op) nodes.set(String(op.id), op);
-      if (impl.edge) {
-        const implEvidence = JSON.parse(String(impl.edge.evidence_json || "{}"));
-        const handlerNode = impl.edge.status === "resolved" ? handlerMethodNode(db, impl.edge.to_id) : void 0;
-        if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
-        edges.push({ step: 1, type: "operation_implemented_by_handler", from: op?.label ? String(op.label) : `${start.servicePath}/${startOperation ?? ""}`, to: handlerNode?.label ? String(handlerNode.label) : `${impl.edge.to_kind}:${impl.edge.to_id}`, evidence: implEvidence, confidence: Number(impl.edge.confidence ?? 0), unresolvedReason: impl.edge.status === "resolved" ? void 0 : String(impl.edge.unresolved_reason ?? impl.edge.status) });
-      }
+  if (scope.startOperationId) {
+    const op = operationNode(db, scope.startOperationId);
+    const impl = implementationScope(db, scope.startOperationId);
+    if (op) nodes.set(String(op.id), op);
+    if (impl.edge) {
+      const implEvidence = { ...parseEvidence(impl.edge.evidence_json), startResolution: { strategy: "indexed_operation_graph", matchedOperationId: scope.startOperationId, implementationEdgeId: impl.edge.id, implementationStatus: impl.edge.status, selectedHandlerMethodId: impl.edge.status === "resolved" ? impl.edge.to_id : void 0 } };
+      const handlerNode = impl.edge.status === "resolved" ? handlerMethodNode(db, impl.edge.to_id) : void 0;
+      if (handlerNode) nodes.set(String(handlerNode.id), handlerNode);
+      seenEdges.add(Number(impl.edge.id));
+      edges.push({ step: 1, type: "operation_implemented_by_handler", from: op?.label ? String(op.label) : `operation:${scope.startOperationId}`, to: handlerNode?.label ? String(handlerNode.label) : `${impl.edge.to_kind}:${impl.edge.to_id}`, evidence: implEvidence, confidence: Number(impl.edge.confidence ?? 0), unresolvedReason: impl.edge.status === "resolved" ? void 0 : String(impl.edge.unresolved_reason ?? impl.edge.status) });
     }
   }
   const seenScopes = /* @__PURE__ */ new Set();
-  const seenEdges = /* @__PURE__ */ new Set();
   while (queue.length > 0) {
     const current = queue.shift();
     if (!current || current.depth > maxDepth) continue;
@@ -2717,4 +2867,4 @@ export {
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-UHYHSYCS.js.map
+//# sourceMappingURL=chunk-AM2JZFQ6.js.map