@saptools/service-flow 0.1.45 → 0.1.46

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.46
+
+- Improved ambiguous implementation diagnostics with ready-to-copy scoped hint suggestions for each blocked helper hop.
+- Persisted deterministic service-client ownership across helper boundaries, object and tuple destructuring, returned clients, and transaction aliases while preserving dynamic evidence for ambiguous flows.
+- Tightened OData operation-invocation normalization and dynamic wrapper-path evidence without promoting entity addressing paths to operation calls.
+- Kept strict doctor output concise by default with actionable categories and detail-mode evidence expansion.
+
 ## 0.1.45
 
 - Added repeatable scoped implementation hints with explicit selection and mismatch evidence while preserving conservative automatic and legacy repository selection.

package/dist/{chunk-BXSCE5CR.js → chunk-EGY2A4AT.js}

@@ -2316,6 +2316,171 @@ function substituteVariables(template, vars) {
   };
 }
 
+// src/trace/implementation-hints.ts
+function parseImplementationHint(value) {
+  const hint = {};
+  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 };
+}
+function selectImplementation(rawEvidence, hints, legacyRepo) {
+  const evidence = asEvidence(rawEvidence);
+  const scoped = hints ?? [];
+  const matchingHints = scoped.filter((hint2) => hintMatchesEdge(hint2, 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" } };
+}
+function implementationHintDiagnostic(selection, suggestions) {
+  if (!selection.blocksAutomatic || selection.methodId) return void 0;
+  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 : void 0,
+    implementationSelection: selection.evidence
+  };
+}
+function implementationHintSuggestions(rawEvidence) {
+  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) {
+  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, key, value) {
+  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, hint, strategy) {
+  const matches2 = (evidence.candidates ?? []).filter((candidate) => candidate.accepted && candidateMatchesRepo(candidate, hint.implementationRepo));
+  const selected = matches2.length === 1 ? matches2[0] : void 0;
+  if (!selected || selected.methodId === void 0) {
+    return {
+      blocksAutomatic: true,
+      evidence: {
+        status: matches2.length > 1 ? "tied" : "not_matched",
+        reason: matches2.length > 1 ? "hint_matched_multiple_candidates" : "hint_matched_zero_candidates",
+        strategy,
+        matchedHint: hint,
+        selectedRepo: hint.implementationRepo,
+        candidateCount: matches2.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, candidate, repo) {
+  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, candidate) {
+  const family = candidate.handlerPackage?.packageName;
+  if (!family) return void 0;
+  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 : void 0;
+}
+function hintString(hint) {
+  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, evidence) {
+  const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
+  const familyNames = /* @__PURE__ */ 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, value) {
+  return candidate.handlerPackage?.name === value || candidate.handlerPackage?.packageName === value || candidate.sourceFile?.startsWith(value) === true;
+}
+function matches(expected, actual) {
+  return expected === void 0 || expected === actual;
+}
+function legacyHint(implementationRepo) {
+  return { implementationRepo };
+}
+function asEvidence(value) {
+  return value;
+}
+
 // src/linker/remote-query-target.ts
 function buildRemoteQueryTarget(input) {
   const entity = typeof input.queryEntity === "string" && input.queryEntity.trim() ? input.queryEntity.trim() : void 0;
@@ -2760,13 +2925,14 @@ function linkImplementations(db, workspaceId, generation) {
       candidateFamilies: duplicateFamilies,
       candidates: candidates.map((candidate, index) => candidateEvidence(candidate, index + 1))
     };
+    const evidenceWithHints = unique ? evidence : { ...evidence, implementationHintSuggestions: implementationHintSuggestions(evidence) };
     if (accepted.length === 0) {
-      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, "OPERATION_IMPLEMENTED_BY_HANDLER", "unresolved", "operation", graphId(operation.operationId), "handler_method_candidates", candidates.map((row) => graphId(row.methodId)).join(","), 0, JSON.stringify(evidence), 0, "No implementation candidate passed policy", generation);
+      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, "OPERATION_IMPLEMENTED_BY_HANDLER", "unresolved", "operation", graphId(operation.operationId), "handler_method_candidates", candidates.map((row) => graphId(row.methodId)).join(","), 0, JSON.stringify(evidenceWithHints), 0, "No implementation candidate passed policy", generation);
       edgeCount += 1;
       unresolvedCount += 1;
       continue;
     }
-    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, "OPERATION_IMPLEMENTED_BY_HANDLER", unique ? "resolved" : "ambiguous", "operation", graphId(operation.operationId), unique ? "handler_method" : "handler_method_candidates", unique ? graphId(unique.methodId) : selected.map((row) => graphId(row.methodId)).join(","), unique ? 0.95 : 0.5, JSON.stringify(evidence), 0, unique ? null : "Ambiguous registered handler implementation candidates", generation);
+    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, "OPERATION_IMPLEMENTED_BY_HANDLER", unique ? "resolved" : "ambiguous", "operation", graphId(operation.operationId), unique ? "handler_method" : "handler_method_candidates", unique ? graphId(unique.methodId) : selected.map((row) => graphId(row.methodId)).join(","), unique ? 0.95 : 0.5, JSON.stringify(evidenceWithHints), 0, unique ? null : "Ambiguous registered handler implementation candidates", generation);
     edgeCount += 1;
     if (unique) resolvedCount += 1;
     else ambiguousCount += 1;
@@ -3005,112 +3171,6 @@ function normalizedOperation(value) {
   return value.startsWith("/") ? value.slice(1) : value;
 }
 
-// src/trace/implementation-hints.ts
-function parseImplementationHint(value) {
-  const hint = {};
-  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 };
-}
-function selectImplementation(rawEvidence, hints, legacyRepo) {
-  const evidence = asEvidence(rawEvidence);
-  const scoped = hints ?? [];
-  const matchingHints = scoped.filter((hint2) => hintMatchesEdge(hint2, 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" } };
-}
-function implementationHintDiagnostic(selection) {
-  if (!selection.blocksAutomatic || selection.methodId) return void 0;
-  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,
-    implementationSelection: selection.evidence
-  };
-}
-function assignHintField(hint, key, value) {
-  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, hint, strategy) {
-  const matches2 = (evidence.candidates ?? []).filter((candidate) => candidate.accepted && candidateMatchesRepo(candidate, hint.implementationRepo));
-  const selected = matches2.length === 1 ? matches2[0] : void 0;
-  if (!selected || selected.methodId === void 0) {
-    return {
-      blocksAutomatic: true,
-      evidence: {
-        status: matches2.length > 1 ? "tied" : "not_matched",
-        reason: matches2.length > 1 ? "hint_matched_multiple_candidates" : "hint_matched_zero_candidates",
-        strategy,
-        matchedHint: hint,
-        selectedRepo: hint.implementationRepo,
-        candidateCount: matches2.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 hintMatchesEdge(hint, evidence) {
-  const model = evidence.modelPackage ?? evidence.candidates?.[0]?.modelPackage;
-  const familyNames = /* @__PURE__ */ 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, value) {
-  return candidate.handlerPackage?.name === value || candidate.handlerPackage?.packageName === value || candidate.sourceFile?.startsWith(value) === true;
-}
-function matches(expected, actual) {
-  return expected === void 0 || expected === actual;
-}
-function legacyHint(implementationRepo) {
-  return { implementationRepo };
-}
-function asEvidence(value) {
-  return value;
-}
-
 // src/trace/evidence.ts
 function baseTraceEvidence(row, call, persistedEvidence, contextualEvidence) {
   const evidence = { ...persistedEvidence, ...contextualEvidence ?? {} };
@@ -3292,8 +3352,8 @@ function operationStartScope(db, repoId, start, hintOptions) {
   }
   if (impl.edge) {
     const evidence = parseEvidence(impl.edge.evidence_json);
-    const hintDiagnostic = implementationHintDiagnostic(hinted);
-    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, candidates: evidence.candidates }];
+    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, implementationHintSuggestions: evidence.implementationHintSuggestions, candidates: evidence.candidates }];
     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" }] };
@@ -3691,9 +3751,9 @@ function trace(db, start, options) {
           const contextMethodId = contextSelection.methodId;
           const contextNode = contextMethodId ? handlerMethodNode(db, contextMethodId) : void 0;
           if (implementation.edge) {
-            const hintDiagnostic = implementationHintDiagnostic(contextSelection);
-            if (hintDiagnostic) diagnostics.unshift(hintDiagnostic);
             const implEvidence = JSON.parse(String(implementation.edge.evidence_json || "{}"));
+            const hintDiagnostic = implementationHintDiagnostic(contextSelection, implEvidence.implementationHintSuggestions);
+            if (hintDiagnostic) diagnostics.unshift(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);
@@ -3761,8 +3821,9 @@ export {
   applyVariables,
   extractPlaceholders,
   substituteVariables,
-  linkWorkspace,
   parseImplementationHint,
+  implementationHintSuggestions,
+  linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-BXSCE5CR.js.map
+//# sourceMappingURL=chunk-EGY2A4AT.js.map