@saptools/service-flow 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.7
+
+- Added atomic last-good repository publication so failed source reads preserve the previous complete snapshot and fingerprint.
+- Added explicit graph freshness metadata and stale diagnostics after successful fact changes until relink.
+- Persisted handler registration class/import evidence and linked registered cross-package implementation handlers through application dependency evidence.
+- Made service-only trace selectors return a typed narrowing diagnostic instead of workspace-wide traversal.
+- Expanded link summaries with dependency and implementation categories whose totals reconcile with persisted graph edges.
+- Preserved terminal parser warning evidence separately from routing status.
+
+
+## 0.1.6
+
+- Scoped runtime variable resolution to eligible dynamic, ambiguous, or unresolved remote edges with matching placeholders, preserving terminal and static resolved edge status, target, reason, and confidence.
+- Clamped operation-resolution confidence to the `[0, 1]` range and retained original runtime expressions alongside effective substitutions and missing-variable evidence.
+- Resolved helper/package dependency graph edges primarily by indexed package name, persisted ambiguous dependency candidates with evidence, and marked inserted helper edges with explicit statuses.
+- Expanded repository fingerprints to include normalized package metadata, full `cds.requires`, scripts, package file content, and the analyzer version so metadata-only changes invalidate stale facts.
+- Replaced the hard-coded CLI version with package metadata as the release source of truth and documented selector, graph variable, SQLite, fingerprint, freshness, and parser-warning semantics.
+
 ## 0.1.5
 
 - Runtime `--var` substitution now re-runs operation resolution in memory for trace and graph output, clears stale unresolved reasons on exact matches, and traverses into the matched downstream handler without mutating the persisted graph.

package/README.md

@@ -47,10 +47,21 @@ npm install @saptools/service-flow
 ```
 
 > [!NOTE]
-> Requires **Node.js ≥ 20**. Version 0.1.5 uses a persistent SQLite driver (`node:sqlite` in supported Node builds) for bound parameters, transactions, WAL, busy timeouts, and read-only query commands. The analyzer is static: it reads files and package metadata, but it does not start CAP services, connect to SAP BTP, or execute application code.
+> Requires **Node.js ≥ 24.0.0** for the bundled `node:sqlite` runtime. Version 0.1.7 uses a persistent SQLite driver (`node:sqlite` in supported Node builds) for bound parameters, transactions, WAL, busy timeouts, and read-only query commands. The analyzer is static: it reads files and package metadata, but it does not start CAP services, connect to SAP BTP, or execute application code.
 
 ---
 
+
+### Correctness notes for 0.1.7
+
+- Runtime `--var` values are considered only for dynamic, ambiguous, or unresolved **remote** graph edges whose alias, destination, service path, or operation path expressions contain supplied placeholders. Local database, external HTTP, event, and already resolved static edges keep their persisted status, target, reason, and confidence. Partial substitutions remain dynamic and report the missing placeholder names.
+- `trace` and `graph` both accept repeatable `--var key=value` options. Effective substitutions are rendered in trace evidence without mutating the persisted graph. Confidence values are bounded to `[0, 1]`.
+- Repository selectors on list, trace, graph, and inspect commands narrow scope. Unknown selectors return empty machine-readable diagnostics instead of falling back to the whole workspace.
+- Helper-package dependency edges prefer exact indexed package names. Duplicate package-name candidates are persisted as ambiguous evidence rather than silently selecting one repository.
+- Repository fingerprints include source content, package name/version, dependencies and devDependencies, scripts, normalized `cds.requires` (including nested credentials), package file content, and the analyzer version. Metadata-only changes therefore trigger reindexing.
+- Index publication is designed around the last-good snapshot: failed parse or persistence attempts are recorded as diagnostics and must not be mixed with older graph facts. After indexing changes, relink before relying on graph/trace output; doctor reports stale or inconsistent stores where detectable.
+- Parser warnings describe analysis completeness, while routing status describes graph behavior. A terminal DB edge can remain terminal while still exposing parser warning evidence about an unknown entity.
+
 ## 🚀 Quick Start
 
 ```bash
@@ -425,3 +436,20 @@ MIT
 ---
 
 Made with ❤️ to make your work life easier!
+
+
+### Service-only trace policy
+
+`service-flow trace --service <path>` is intentionally not a broad workspace traversal. Provide `--operation`, `--path`, or `--handler`; otherwise the command returns a typed `trace_start_not_found` diagnostic and no edges.
+
+### Graph freshness and last-good snapshots
+
+Repository facts are parsed before publication and committed atomically. Failed indexing attempts record diagnostics and retain the last complete published snapshot and successful fingerprint. Successful fact publication marks the workspace graph stale until `service-flow link` rebuilds dependency, remote-call, and implementation edges for the current fact generation.
+
+### Cross-package implementation evidence
+
+Handler registrations persist parsed class names and import sources. Linking resolves implementation edges only through registered application evidence plus model and handler package dependency edges; a decorator-name match alone is not enough.
+
+### Graph variables
+
+The `graph` command accepts repeatable `--var key=value` options, matching `trace`, for runtime substitution previews in JSON or Mermaid output.

package/TECHNICAL-NOTE.md

@@ -1,4 +1,4 @@
-# Service Flow 0.1.5 Resolution Notes
+# Service Flow 0.1.7 Resolution Notes
 
 - Imported helper bindings: TypeScript imports are resolved for relative modules. When a caller assigns `const client = await connectToService()`, the analyzer follows the imported symbol to an exported helper that returns `cds.connect.to(...)` and persists caller-variable evidence plus the helper source/export chain.
 - Candidate ranking: operation-path matches start as weak candidates. A resolved operation edge requires a strong signal such as exact service path, CDS alias/destination context, or explicit dynamic variable overrides. Otherwise candidates are preserved in edge evidence as ambiguous or unresolved.
@@ -19,3 +19,13 @@
 - Edge evidence and target operation provenance are separate: call file/line and helper chains stay on the edge, while operation nodes are loaded from CDS operation/service/repository rows.
 - The linker stores explicit edge status categories and summary counts. Valid DB, event, and external terminals keep `unresolved_reason` null.
 - Repository-level fingerprints include source paths/hashes, package dependencies, and analyzer schema version. Unchanged repositories are skipped unless `--force` is used.
+
+
+## 0.1.7 correctness additions
+
+- Runtime resolution now has an explicit eligibility gate: only remote dynamic/ambiguous/unresolved graph edges with affected placeholders are re-resolved in memory. Terminal and resolved static edges are copied through unchanged, and substitutions keep original expressions, effective values, supplied variables, and missing variables separate.
+- Operation candidate scores are clamped into `[0, 1]` before graph or trace rendering.
+- Helper package linking uses exact `repositories.package_name` matches before normalized directory-name fallback. Ambiguous package names are represented as ambiguous graph edges with all candidates in evidence.
+- Fingerprints hash normalized package facts and package bytes in addition to source file paths/content and analyzer version.
+- The CLI version imports package metadata, so package metadata, `service-flow --version`, changelog, and analyzer/fingerprint version share one release source.
+- Supported runtime is Node.js 24+ with `node:sqlite` validation; older runtimes should fail with a compatibility message instead of a late `DatabaseSync` error.

package/dist/{chunk-I33ASGX3.js → chunk-YFT57U54.js}

@@ -336,6 +336,14 @@ function lineOf2(text, idx) {
 async function parseHandlerRegistrations(repoPath, filePath) {
   const text = await fs5.readFile(path6.join(repoPath, filePath), "utf8");
   const out = [];
+  const imports = /* @__PURE__ */ new Map();
+  for (const m of text.matchAll(/import\s+\{?\s*([A-Za-z0-9_,\s]+)\s*\}?\s+from\s+['"]([^'"]+)['"]/g)) {
+    const source = m[2];
+    for (const name of (m[1] ?? "").split(",")) {
+      const symbol = name.trim().split(/\s+as\s+/).pop()?.trim();
+      if (symbol) imports.set(symbol, source);
+    }
+  }
   for (const m of text.matchAll(
     /createCombinedHandler\s*\(|srv\.prepend\s*\(|cds\.serve\s*\(/g
   ))
@@ -351,6 +359,7 @@ async function parseHandlerRegistrations(repoPath, filePath) {
     for (const c of (m[1] ?? "").matchAll(/\b(\w+Handler)\b/g))
       out.push({
         className: c[1],
+        importSource: imports.get(c[1]),
         registrationFile: normalizePath(filePath),
         registrationLine: lineOf2(text, (m.index ?? 0) + (c.index ?? 0)),
         registrationKind: "handler-array",
@@ -873,12 +882,30 @@ function collectClassHelpers(sf) {
 }
 
 // src/linker/dynamic-edge-resolver.ts
+var PLACEHOLDER = /\$\{\s*(\w+)\s*\}/g;
 function applyVariables(template, vars) {
-  if (!template) return void 0;
-  return template.replace(
-    /\$\{\s*(\w+)\s*\}/g,
-    (_m, key) => vars[key] ?? `\${${key}}`
+  return substituteVariables(template, vars).effective;
+}
+function extractPlaceholders(template) {
+  return [...(template ?? "").matchAll(PLACEHOLDER)].map((m) => m[1] ?? "").filter(Boolean);
+}
+function substituteVariables(template, vars) {
+  if (!template) return { placeholders: [], missing: [], supplied: [], changed: false };
+  const placeholders2 = [...new Set(extractPlaceholders(template))];
+  const supplied = placeholders2.filter((key) => Object.hasOwn(vars, key));
+  const missing = placeholders2.filter((key) => !Object.hasOwn(vars, key));
+  const effective = template.replace(
+    PLACEHOLDER,
+    (_m, key) => Object.hasOwn(vars, key) ? vars[key] ?? "" : `\${${key}}`
   );
+  return {
+    original: template,
+    effective,
+    placeholders: placeholders2,
+    missing,
+    supplied,
+    changed: effective !== template
+  };
 }
 
 // src/linker/service-resolver.ts
@@ -936,6 +963,7 @@ function resolveOperation(db, signals, workspaceId) {
       c.reasons.push("explicit_dynamic_override");
     }
   }
+  for (const c of candidates) c.score = Math.max(0, Math.min(1, c.score));
   candidates.sort(
     (a, b) => b.score - a.score || a.repoName.localeCompare(b.repoName)
   );
@@ -968,138 +996,125 @@ function resolveOperation(db, signals, workspaceId) {
 }
 
 // src/linker/helper-package-linker.ts
-function linkHelperPackages(db, workspaceId) {
-  const repos = db.prepare(
-    "SELECT id,name,dependencies_json FROM repositories WHERE workspace_id=?"
-  ).all(workspaceId);
-  let count = 0;
+function normalizeName(value) {
+  return value.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "");
+}
+function candidatesForDependency(repos, dep, sourceId) {
+  const exact = repos.filter((repo) => repo.id !== sourceId && repo.package_name === dep);
+  if (exact.length > 0) return { candidates: exact, strategy: "exact_package_name" };
+  const normalized = normalizeName(dep);
+  return { candidates: repos.filter((repo) => repo.id !== sourceId && normalizeName(repo.name) === normalized), strategy: "normalized_directory" };
+}
+function linkHelperPackages(db, workspaceId, generation) {
+  const repos = db.prepare("SELECT id,name,package_name,dependencies_json FROM repositories WHERE workspace_id=?").all(workspaceId);
+  const summary = { edgeCount: 0, resolvedCount: 0, ambiguousCount: 0 };
   for (const repo of repos) {
     const deps = JSON.parse(repo.dependencies_json);
     for (const dep of Object.keys(deps)) {
-      const helper = repos.find((r) => r.name === dep || dep.endsWith(r.name));
-      if (helper) {
-        db.prepare(
-          "INSERT INTO graph_edges(workspace_id,edge_type,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic) VALUES(?,?,?,?,?,?,?,?,?)"
-        ).run(
-          workspaceId,
-          "REPO_IMPORTS_HELPER_PACKAGE",
-          "repo",
-          String(repo.id),
-          "repo",
-          String(helper.id),
-          0.9,
-          JSON.stringify({ dependency: dep }),
-          0
-        );
-        count += 1;
-      }
+      const result = candidatesForDependency(repos, dep, repo.id);
+      if (result.candidates.length === 0) continue;
+      const status = result.candidates.length === 1 ? "resolved" : "ambiguous";
+      const helper = status === "resolved" ? result.candidates[0] : void 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,
+        "REPO_IMPORTS_HELPER_PACKAGE",
+        status,
+        "repo",
+        String(repo.id),
+        helper ? "repo" : "repo_candidates",
+        helper ? String(helper.id) : result.candidates.map((candidate) => candidate.id).join(","),
+        helper ? 1 : 0.5,
+        JSON.stringify({ dependency: dep, candidates: result.candidates.map((candidate) => ({ id: candidate.id, name: candidate.name, packageName: candidate.package_name })), match: result.strategy }),
+        0,
+        helper ? null : "Ambiguous dependency package candidates",
+        generation
+      );
+      summary.edgeCount += 1;
+      if (helper) summary.resolvedCount += 1;
+      else summary.ambiguousCount += 1;
     }
   }
-  return count;
+  return summary;
 }
 
 // src/linker/cross-repo-linker.ts
 function linkWorkspace(db, workspaceId, vars = {}) {
   return db.transaction(() => {
+    const generation = nextGraphGeneration(db, workspaceId);
     db.prepare("DELETE FROM graph_edges WHERE workspace_id=?").run(workspaceId);
-    let edges = linkHelperPackages(db, workspaceId);
-    let unresolved = 0;
-    let resolvedCount = 0;
-    let ambiguousCount = 0;
-    let dynamicCount = 0;
-    let terminalCount = 0;
-    const calls = db.prepare(
-      `SELECT c.*,r.name repoName,b.alias,b.alias_expr aliasExpr,b.destination_expr destinationExpr,b.service_path_expr servicePathExpr,b.is_dynamic isDynamic,b.placeholders_json placeholdersJson,b.helper_chain_json helperChainJson,req.service_path requireServicePath,req.destination requireDestination FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id LEFT JOIN service_bindings b ON b.id=c.service_binding_id LEFT JOIN cds_requires req ON req.repo_id=c.repo_id AND req.alias=b.alias WHERE r.workspace_id=?`
-    ).all(workspaceId);
-    for (const call of calls) {
-      const callType = String(call.call_type);
-      const op = applyVariables(String(call.operation_path_expr ?? ""), vars);
-      const servicePath = applyVariables(
-        call.servicePathExpr ?? call.requireServicePath,
-        vars
-      );
-      const destination = call.destinationExpr ?? call.requireDestination;
-      const isDynamic = Boolean(Number(call.isDynamic ?? 0));
-      const resolution = callType.startsWith("remote") ? resolveOperation(
-        db,
-        {
-          servicePath,
-          operationPath: op,
-          alias: applyVariables(call.aliasExpr ?? call.alias, vars),
-          destination: applyVariables(destination, vars),
-          isDynamic,
-          hasExplicitOverride: Object.keys(vars).length > 0
-        },
-        workspaceId
-      ) : { status: "unresolved", candidates: [], reasons: [] };
-      const target = resolution.target;
-      const evidence = {
-        sourceFile: call.source_file,
-        sourceLine: call.source_line,
-        file: call.source_file,
-        line: call.source_line,
-        repo: call.repoName,
-        serviceAlias: call.alias,
-        serviceAliasExpr: call.aliasExpr,
-        destination: applyVariables(destination, vars),
-        servicePath,
-        operationPath: op,
-        targetRepo: target?.repoName,
-        targetOperation: target?.operationName,
-        helperChain: call.helperChainJson ? JSON.parse(String(call.helperChainJson)) : void 0,
-        candidates: resolution.candidates,
-        candidateCount: resolution.candidates.length,
-        resolutionStatus: resolution.status,
-        resolutionReasons: resolution.reasons
-      };
-      if (target) {
-        db.prepare(
-          "INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic) VALUES(?,?,?,?,?,?,?,?,?,?)"
-        ).run(
-          workspaceId,
-          "REMOTE_CALL_RESOLVES_TO_OPERATION",
-          "resolved",
-          "call",
-          String(call.id),
-          "operation",
-          String(target.operationId),
-          target.score,
-          JSON.stringify(evidence),
-          isDynamic ? 1 : 0
-        );
-        edges += 1;
-        resolvedCount += 1;
-      } else {
-        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 ?? (resolution.status === "ambiguous" ? "Ambiguous operation candidates require a strong service signal" : resolution.status === "dynamic" ? `Dynamic target requires runtime variable overrides: ${(resolution.reasons.length ? resolution.reasons : ["missing runtime variables"]).join(", ")}` : "No indexed target operation matched")
-        );
-        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) VALUES(?,?,?,?,?,?,?,?,?,?,?)"
-        ).run(
-          workspaceId,
-          edgeType,
-          status,
-          "call",
-          String(call.id),
-          callType.startsWith("async_") ? "event" : "external",
-          String(call.event_name_expr ?? call.query_entity ?? op ?? call.id),
-          Number(call.confidence ?? 0.2),
-          JSON.stringify(evidence),
-          isDynamic || resolution.status === "dynamic" ? 1 : 0,
-          unresolvedReason
-        );
-        edges += 1;
-        unresolved += status === "unresolved" ? 1 : 0;
-        ambiguousCount += status === "ambiguous" ? 1 : 0;
-        dynamicCount += status === "dynamic" ? 1 : 0;
-        terminalCount += status === "terminal" ? 1 : 0;
-      }
-    }
-    return { edgeCount: edges, unresolvedCount: unresolved, resolvedCount, ambiguousCount, dynamicCount, terminalCount };
+    const deps = linkHelperPackages(db, workspaceId, generation);
+    const callSummary = linkCalls(db, workspaceId, vars, generation);
+    const impl = linkImplementations(db, workspaceId, generation);
+    db.prepare("UPDATE repositories SET graph_generation=?, graph_stale_reason=NULL, graph_stale_at=NULL WHERE workspace_id=?").run(generation, workspaceId);
+    return { ...callSummary, edgeCount: deps.edgeCount + callSummary.edgeCount + impl.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount };
   });
 }
+function nextGraphGeneration(db, workspaceId) {
+  const row = db.prepare("SELECT COALESCE(MAX(graph_generation),0) generation FROM repositories WHERE workspace_id=?").get(workspaceId);
+  return Number(row?.generation ?? 0) + 1;
+}
+function linkCalls(db, workspaceId, vars, generation) {
+  let edgeCount = 0;
+  let unresolvedCount = 0;
+  let resolvedCount = 0;
+  let ambiguousCount = 0;
+  let dynamicCount = 0;
+  let terminalCount = 0;
+  const calls = db.prepare(`SELECT c.*,r.name repoName,b.alias,b.alias_expr aliasExpr,b.destination_expr destinationExpr,b.service_path_expr servicePathExpr,b.is_dynamic isDynamic,b.placeholders_json placeholdersJson,b.helper_chain_json helperChainJson,req.service_path requireServicePath,req.destination requireDestination FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id LEFT JOIN service_bindings b ON b.id=c.service_binding_id LEFT JOIN cds_requires req ON req.repo_id=c.repo_id AND req.alias=b.alias WHERE r.workspace_id=?`).all(workspaceId);
+  for (const call of calls) {
+    const result = insertCallEdge(db, workspaceId, call, vars, generation);
+    edgeCount += 1;
+    resolvedCount += result.status === "resolved" ? 1 : 0;
+    unresolvedCount += result.status === "unresolved" ? 1 : 0;
+    ambiguousCount += result.status === "ambiguous" ? 1 : 0;
+    dynamicCount += result.status === "dynamic" ? 1 : 0;
+    terminalCount += result.status === "terminal" ? 1 : 0;
+  }
+  return { edgeCount, unresolvedCount, resolvedCount, ambiguousCount, dynamicCount, terminalCount };
+}
+function insertCallEdge(db, workspaceId, call, vars, generation) {
+  const callType = String(call.call_type);
+  const op = applyVariables(String(call.operation_path_expr ?? ""), vars);
+  const servicePath = applyVariables(call.servicePathExpr ?? call.requireServicePath, vars);
+  const destination = call.destinationExpr ?? call.requireDestination;
+  const isDynamic = Boolean(Number(call.isDynamic ?? 0));
+  const resolution = callType.startsWith("remote") ? resolveOperation(db, { servicePath, operationPath: op, alias: applyVariables(call.aliasExpr ?? call.alias, vars), destination: destination ? applyVariables(destination, vars) : void 0, isDynamic, hasExplicitOverride: Object.keys(vars).length > 0 }, workspaceId) : { status: "unresolved", candidates: [], reasons: [] };
+  const evidence = callEvidence(call, resolution, servicePath, op, destination ? applyVariables(destination, vars) : void 0);
+  if (resolution.target) {
+    db.prepare("INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?)").run(workspaceId, "REMOTE_CALL_RESOLVES_TO_OPERATION", "resolved", "call", String(call.id), "operation", String(resolution.target.operationId), resolution.target.score, JSON.stringify(evidence), isDynamic ? 1 : 0, generation);
+    return { status: "resolved" };
+  }
+  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 ?? (resolution.status === "ambiguous" ? "Ambiguous operation candidates require a strong service signal" : resolution.status === "dynamic" ? `Dynamic target requires runtime variable overrides: ${(resolution.reasons.length ? resolution.reasons : ["missing runtime variables"]).join(", ")}` : "No indexed target operation matched"));
+  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), callType.startsWith("async_") ? "event" : "external", String(call.event_name_expr ?? call.query_entity ?? op ?? call.id), Number(call.confidence ?? 0.2), JSON.stringify(evidence), isDynamic || resolution.status === "dynamic" ? 1 : 0, unresolvedReason, generation);
+  return { status };
+}
+function callEvidence(call, resolution, servicePath, op, destination) {
+  return { sourceFile: call.source_file, sourceLine: call.source_line, file: call.source_file, line: call.source_line, repo: call.repoName, serviceAlias: call.alias, serviceAliasExpr: call.aliasExpr, destination, servicePath, operationPath: op, targetRepo: resolution.target?.repoName, targetOperation: resolution.target?.operationName, helperChain: call.helperChainJson ? JSON.parse(String(call.helperChainJson)) : void 0, candidates: resolution.candidates, candidateCount: resolution.candidates.length, resolutionStatus: resolution.status, resolutionReasons: resolution.reasons, analysisCompleteness: call.unresolved_reason ? "partial" : "complete", parserWarning: call.unresolved_reason ? { code: "parser_warning", message: call.unresolved_reason } : void 0 };
+}
+function linkImplementations(db, workspaceId, generation) {
+  const operations = db.prepare(`SELECT o.id operationId,o.operation_path operationPath,o.operation_name operationName,s.service_path servicePath,s.repo_id modelRepoId,r.package_name modelPackage FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE r.workspace_id=?`).all(workspaceId);
+  let edgeCount = 0;
+  let resolvedCount = 0;
+  let ambiguousCount = 0;
+  for (const operation of operations) {
+    const rows2 = implementationCandidates(db, workspaceId, operation);
+    if (rows2.length === 0) continue;
+    const unique = rows2.length === 1 ? rows2[0] : void 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", unique ? "resolved" : "ambiguous", "operation", String(operation.operationId), unique ? "handler_method" : "handler_method_candidates", unique ? String(unique.methodId) : rows2.map((row) => row.methodId).join(","), unique ? 0.95 : 0.5, JSON.stringify({ servicePath: operation.servicePath, operationPath: operation.operationPath, operationName: operation.operationName, candidates: rows2, evidence: "registered_application_dependency" }), 0, unique ? null : "Ambiguous registered handler implementation candidates", generation);
+    edgeCount += 1;
+    if (unique) resolvedCount += 1;
+    else ambiguousCount += 1;
+  }
+  return { edgeCount, resolvedCount, ambiguousCount };
+}
+function implementationCandidates(db, workspaceId, operation) {
+  return db.prepare(`SELECT DISTINCT hm.id methodId,hc.id classId,hc.class_name className,hc.source_file sourceFile,hc.source_line sourceLine,hr.repo_id applicationRepoId,handlerRepo.name handlerRepo,appRepo.name applicationRepo FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id JOIN repositories handlerRepo ON handlerRepo.id=hc.repo_id JOIN handler_registrations hr ON hr.class_name=hc.class_name JOIN repositories appRepo ON appRepo.id=hr.repo_id JOIN graph_edges modelDep ON modelDep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND modelDep.status='resolved' AND modelDep.from_kind='repo' AND modelDep.from_id=CAST(appRepo.id AS TEXT) AND modelDep.to_id=CAST(? AS TEXT) JOIN graph_edges handlerDep ON handlerDep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND handlerDep.status='resolved' AND handlerDep.from_kind='repo' AND handlerDep.from_id=CAST(appRepo.id AS TEXT) AND handlerDep.to_id=CAST(handlerRepo.id AS TEXT) WHERE appRepo.workspace_id=? AND (hm.decorator_value=? OR hm.decorator_value=? OR hm.method_name=?)`).all(operation.modelRepoId, workspaceId, normalizedOperation(String(operation.operationPath ?? "")), operation.operationName, operation.operationName);
+}
+function normalizedOperation(value) {
+  return value.startsWith("/") ? value.slice(1) : value;
+}
 
 // src/trace/trace-engine.ts
 function normalizeOperation(value) {
@@ -1147,8 +1162,10 @@ function startScope(db, start) {
   if (start.repo && !repo) return { repo, selectorMatched: false };
   const sourceFiles = sourceFilesForStart(db, repo?.id, start);
   const hasSelector = Boolean(
-    start.handler ?? start.operation ?? start.operationPath
+    start.handler ?? start.operation ?? start.operationPath ?? start.servicePath
   );
+  if (start.servicePath && !start.operation && !start.operationPath && !start.handler)
+    return { repo, selectorMatched: false };
   return {
     repo,
     sourceFiles,
@@ -1169,6 +1186,12 @@ function handlerFilesForOperation(db, operationId) {
   ).all(op.repoId, operation, operation, op.operationName);
   return new Set(rows2.map((row) => row.sourceFile).filter(Boolean));
 }
+function implementationScope(db, operationId) {
+  const edge = db.prepare("SELECT * FROM graph_edges WHERE edge_type='OPERATION_IMPLEMENTED_BY_HANDLER' AND status='resolved' AND from_kind='operation' AND from_id=? ORDER BY id LIMIT 1").get(operationId);
+  if (!edge) return { files: /* @__PURE__ */ new Set() };
+  const row = db.prepare("SELECT hc.repo_id repoId,hc.source_file sourceFile FROM handler_methods hm JOIN handler_classes hc ON hc.id=hm.handler_class_id WHERE hm.id=?").get(edge.to_id);
+  return { repoId: row?.repoId, files: new Set(row?.sourceFile ? [row.sourceFile] : []) };
+}
 function includeCall(type, options) {
   if (!options.includeDb && type === "local_db_query") return false;
   if (!options.includeExternal && type === "external_http") return false;
@@ -1187,30 +1210,30 @@ function graphForCalls(db, callIds) {
   }
   return map;
 }
-function candidatesFromEvidence(evidence) {
-  return Array.isArray(evidence.candidates) ? evidence.candidates.filter(
-    (candidate) => typeof candidate === "object" && candidate !== null
-  ) : [];
+function hasRuntimeVariable(value, vars) {
+  return typeof value === "string" && extractPlaceholders(value).some((key) => Object.hasOwn(vars, key));
+}
+function isRemoteRuntimeCandidate(row, evidence, vars) {
+  if (!vars || Object.keys(vars).length === 0) return false;
+  if (!["dynamic", "ambiguous", "unresolved"].includes(String(row.status ?? ""))) return false;
+  if (!["DYNAMIC_EDGE_CANDIDATE", "UNRESOLVED_EDGE", "REMOTE_CALL_RESOLVES_TO_OPERATION"].includes(row.edge_type)) return false;
+  if (row.status === "resolved") return false;
+  return ["servicePath", "operationPath", "serviceAliasExpr", "serviceAlias", "destination"].some((key) => hasRuntimeVariable(evidence[key], vars));
 }
 function evidenceWithRuntimeVariables(evidence, vars) {
   if (!vars || Object.keys(vars).length === 0) return evidence;
-  const servicePath = typeof evidence.servicePath === "string" ? applyVariables(evidence.servicePath, vars) : void 0;
-  const operationPath = typeof evidence.operationPath === "string" ? applyVariables(evidence.operationPath, vars) : void 0;
-  const candidates = candidatesFromEvidence(evidence);
-  const matched = servicePath ? candidates.find((candidate) => candidate.servicePath === servicePath) : void 0;
-  return {
-    ...evidence,
-    servicePath: servicePath ?? evidence.servicePath,
-    operationPath: operationPath ?? evidence.operationPath,
-    runtimeVariablesApplied: true,
-    runtimeResolvedCandidate: matched ? {
-      repoName: matched.repoName,
-      servicePath: matched.servicePath,
-      operationPath: matched.operationPath,
-      operationName: matched.operationName,
-      score: matched.score
-    } : void 0
-  };
+  const substitutions = {};
+  for (const key of ["servicePath", "operationPath", "serviceAliasExpr", "serviceAlias", "destination"]) {
+    const substitution = substituteVariables(typeof evidence[key] === "string" ? String(evidence[key]) : void 0, vars);
+    if (substitution.placeholders.length > 0) substitutions[key] = substitution;
+  }
+  const next = { ...evidence, runtimeVariablesApplied: true, runtimeSubstitutions: substitutions };
+  for (const [key, value] of Object.entries(substitutions)) {
+    if (value.effective) next[key] = value.effective;
+  }
+  const missing = Object.values(substitutions).flatMap((value) => value.missing);
+  if (missing.length > 0) next.missingRuntimeVariables = [...new Set(missing)];
+  return next;
 }
 function operationNode(db, operationId) {
   const row = db.prepare(`SELECT o.id operationId,o.operation_name operationName,o.operation_type operationType,o.operation_path operationPath,o.source_file sourceFile,o.source_line sourceLine,s.id serviceId,s.service_name serviceName,s.qualified_name qualifiedName,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 o.id=?`).get(operationId);
@@ -1221,20 +1244,22 @@ function workspaceIdForCall(db, callId) {
   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)?.workspaceId;
 }
 function runtimeResolution(db, row, evidence, vars) {
-  if (!vars || Object.keys(vars).length === 0) return { row, evidence, unresolvedReason: row.unresolved_reason };
+  if (!isRemoteRuntimeCandidate(row, evidence, vars))
+    return { row, evidence, unresolvedReason: row.unresolved_reason };
   const nextEvidence = evidenceWithRuntimeVariables(evidence, vars);
   const servicePath = typeof nextEvidence.servicePath === "string" ? nextEvidence.servicePath : void 0;
   const operationPath = typeof nextEvidence.operationPath === "string" ? nextEvidence.operationPath : void 0;
-  const alias = typeof nextEvidence.serviceAliasExpr === "string" ? applyVariables(nextEvidence.serviceAliasExpr, vars) : typeof nextEvidence.serviceAlias === "string" ? applyVariables(nextEvidence.serviceAlias, vars) : void 0;
-  const destination = typeof nextEvidence.destination === "string" ? applyVariables(nextEvidence.destination, vars) : void 0;
-  const resolution = resolveOperation(db, { servicePath, operationPath, alias, destination, hasExplicitOverride: true, isDynamic: Boolean(row.status === "dynamic" || nextEvidence.resolutionStatus === "dynamic") }, workspaceIdForCall(db, row.from_id));
+  const alias = typeof nextEvidence.serviceAliasExpr === "string" ? nextEvidence.serviceAliasExpr : typeof nextEvidence.serviceAlias === "string" ? nextEvidence.serviceAlias : void 0;
+  const destination = typeof nextEvidence.destination === "string" ? nextEvidence.destination : void 0;
+  const resolution = resolveOperation(db, { servicePath, operationPath, alias, destination, hasExplicitOverride: true, isDynamic: true }, workspaceIdForCall(db, row.from_id));
   nextEvidence.runtimeResolutionStatus = resolution.status;
   nextEvidence.runtimeResolutionReasons = resolution.reasons;
   if (resolution.target) {
     nextEvidence.runtimeResolvedCandidate = resolution.target;
-    return { row: { ...row, to_kind: "operation", to_id: String(resolution.target.operationId), unresolved_reason: void 0, confidence: resolution.target.score }, evidence: nextEvidence, target: resolution.target };
+    return { row: { ...row, to_kind: "operation", to_id: String(resolution.target.operationId), unresolved_reason: void 0, confidence: Math.max(0, Math.min(1, resolution.target.score)) }, evidence: nextEvidence, target: resolution.target };
   }
-  return { row, evidence: nextEvidence, unresolvedReason: resolution.status === "dynamic" ? `Dynamic target is missing runtime variables: ${resolution.reasons.join(", ")}` : resolution.status === "ambiguous" ? "Ambiguous runtime operation candidates" : "No runtime operation candidate matched substituted service and operation path" };
+  const unresolvedReason = resolution.status === "dynamic" ? `Dynamic target is missing runtime variables: ${resolution.reasons.join(", ")}` : resolution.status === "ambiguous" ? "Ambiguous runtime operation candidates" : "No runtime operation candidate matched substituted service and operation path";
+  return { row, evidence: nextEvidence, unresolvedReason };
 }
 function edgeTarget(row, evidence) {
   const runtimeCandidate = evidence.runtimeResolvedCandidate;
@@ -1251,11 +1276,14 @@ function trace(db, start, options) {
   const diagnostics = db.prepare(
     "SELECT severity,code,message,source_file sourceFile,source_line sourceLine FROM diagnostics WHERE (? IS NULL OR repo_id=?)"
   ).all(scope.repo?.id, scope.repo?.id);
+  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)
     diagnostics.unshift({
       severity: "warning",
       code: "trace_start_not_found",
-      message: "No handler source matched the requested trace start selector"
+      message: start.servicePath && !start.operation && !start.operationPath && !start.handler ? "Service-only trace requires --operation or --path and will not broaden to the whole workspace" : "No handler source matched the requested trace start selector"
     });
   const maxDepth = positiveDepth(options.depth);
   const edges = [];
@@ -1317,9 +1345,10 @@ function trace(db, start, options) {
           unresolvedReason: effective.unresolvedReason
         });
         if (effectiveRow.to_kind === "operation" && current.depth < maxDepth) {
-          const files = handlerFilesForOperation(db, effectiveRow.to_id);
+          const implementation = implementationScope(db, effectiveRow.to_id);
+          const files = implementation.files.size > 0 ? implementation.files : handlerFilesForOperation(db, effectiveRow.to_id);
           if (files.size > 0) {
-            const targetRepoId = db.prepare(
+            const targetRepoId = implementation.repoId ?? db.prepare(
               "SELECT s.repo_id repoId FROM cds_operations o JOIN cds_services s ON s.id=o.service_id WHERE o.id=?"
             ).get(effectiveRow.to_id)?.repoId;
             const nextKey = `${targetRepoId ?? "*"}:${[...files].sort().join(",")}`;
@@ -1360,7 +1389,9 @@ export {
   parseOutboundCalls,
   parseServiceBindings,
   applyVariables,
+  extractPlaceholders,
+  substituteVariables,
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-I33ASGX3.js.map
+//# sourceMappingURL=chunk-YFT57U54.js.map