@saptools/service-flow 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.

package/README.md

@@ -47,12 +47,12 @@ npm install @saptools/service-flow
 ```
 
 > [!NOTE]
-> Requires **Node.js ≥ 24.0.0** for the bundled `node:sqlite` runtime. Version 0.1.6 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.6
+### 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]`.
@@ -436,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.6 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.
@@ -21,7 +21,7 @@
 - Repository-level fingerprints include source paths/hashes, package dependencies, and analyzer schema version. Unchanged repositories are skipped unless `--force` is used.
 
 
-## 0.1.6 correctness additions
+## 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.

package/dist/{chunk-6C5HZ6IR.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",
@@ -992,149 +1001,120 @@ function normalizeName(value) {
 }
 function candidatesForDependency(repos, dep, sourceId) {
   const exact = repos.filter((repo) => repo.id !== sourceId && repo.package_name === dep);
-  if (exact.length > 0) return exact;
+  if (exact.length > 0) return { candidates: exact, strategy: "exact_package_name" };
   const normalized = normalizeName(dep);
-  return repos.filter((repo) => repo.id !== sourceId && normalizeName(repo.name) === normalized);
+  return { candidates: repos.filter((repo) => repo.id !== sourceId && normalizeName(repo.name) === normalized), strategy: "normalized_directory" };
 }
-function linkHelperPackages(db, workspaceId) {
-  const repos = db.prepare(
-    "SELECT id,name,package_name,dependencies_json FROM repositories WHERE workspace_id=?"
-  ).all(workspaceId);
-  let count = 0;
+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 candidates = candidatesForDependency(repos, dep, repo.id);
-      if (candidates.length === 0) continue;
-      const status = candidates.length === 1 ? "resolved" : "ambiguous";
-      const helper = candidates.length === 1 ? 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) VALUES(?,?,?,?,?,?,?,?,?,?,?)"
-      ).run(
+      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) : candidates.map((candidate) => candidate.id).join(","),
+        helper ? String(helper.id) : result.candidates.map((candidate) => candidate.id).join(","),
         helper ? 1 : 0.5,
-        JSON.stringify({
-          dependency: dep,
-          candidates: candidates.map((candidate) => ({ id: candidate.id, name: candidate.name, packageName: candidate.package_name })),
-          match: helper?.package_name === dep ? "package_name" : "normalized_directory"
-        }),
+        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"
+        helper ? null : "Ambiguous dependency package candidates",
+        generation
       );
-      count += 1;
+      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) {
@@ -1182,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,
@@ -1204,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;
@@ -1288,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 = [];
@@ -1354,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(",")}`;
@@ -1402,4 +1394,4 @@ export {
   linkWorkspace,
   trace
 };
-//# sourceMappingURL=chunk-6C5HZ6IR.js.map
+//# sourceMappingURL=chunk-YFT57U54.js.map