@saptools/service-flow 0.1.67 → 0.1.69

package/src/trace/020-compact-field-projection.ts

@@ -17,8 +17,15 @@ import type {
   CompactStartV1,
   CompactStatusCountsV1,
 } from './014-compact-contract.js';
+import {
+  compactMissingRemediation,
+  isSafeCompactReferenceName,
+  isSafeCompactSelectorSuggestion,
+  projectCompactReferenceGroup,
+  projectCompactMissingNames,
+  type CompactMissingNameProjection,
+} from './021-compact-decision-normalization.js';
 
-const compactNameLimit = 8;
 const compactDiagnosticMessages: Readonly<Record<string, string>> = {
   schema_upgrade_required: 'The database schema must be upgraded before tracing.',
   reindex_required: 'Current analyzer facts are required before tracing.',
@@ -27,8 +34,19 @@ const compactDiagnosticMessages: Readonly<Record<string, string>> = {
   implementation_hint_mismatch: 'The implementation hint did not select one implementation.',
   selected_handler_provenance_mismatch: 'Selected handler provenance did not match its graph target.',
   selected_handler_target_not_found: 'The selected handler target is not indexed.',
+  trace_start_ambiguous: 'The trace start selector is ambiguous.',
+  trace_start_not_found: 'The trace start selector did not match an indexed start.',
   trace_start_implementation_unresolved: 'The trace start implementation is unresolved.',
 };
+const selectorDiagnosticCodes = new Set([
+  'handler_decorators_not_indexed',
+  'handler_methods_not_indexed',
+  'selector_repo_ambiguous',
+  'selector_repo_not_found',
+  'trace_start_ambiguous',
+  'trace_start_implementation_unresolved',
+  'trace_start_not_found',
+]);
 
 export function projectCompactDecision(
   input: CompactDecisionInput | undefined,
@@ -56,14 +74,10 @@ function resolutionDecision(input: CompactDecisionInput): CompactDecisionV1 {
 }
 
 function addNameDecision(out: CompactDecisionV1, input: CompactDecisionInput): void {
-  const allNames = safeVariableNames(input.missingVariableNames);
-  const names = allNames.slice(0, compactNameLimit);
-  const total = Math.max(compactCount(input.missingVariableCount), allNames.length);
-  if (names.length > 0) out.missingVariableNames = names;
-  if (total === 0) return;
-  out.missingVariableCount = total;
-  out.shownMissingVariableCount = names.length;
-  out.omittedMissingVariableCount = Math.max(0, total - names.length);
+  const projection = projectCompactMissingNames(
+    input.missingVariableNames, input.missingVariableCount,
+  );
+  applyMissingProjection(out, projection);
 }
 
 function addDynamicDecision(out: CompactDecisionV1, input: CompactDecisionInput): void {
@@ -87,6 +101,8 @@ function addImplementationDecision(
     out.implementationGuided = input.implementationGuided;
   if (input.implementationContextual !== undefined)
     out.implementationContextual = input.implementationContextual;
+  if (input.tiedCandidateRepos)
+    out.tiedCandidateRepos = input.tiedCandidateRepos;
 }
 
 function addEventDecision(out: CompactDecisionV1, input: CompactDecisionInput): void {
@@ -117,14 +133,24 @@ function addRemediationDecision(
   out: CompactDecisionV1,
   input: CompactDecisionInput,
 ): void {
-  const hint = input.remediationCode
-    ? compactRemediationHint(input.remediationCode) : undefined;
+  const hint = decisionRemediation(input);
   if (!hint) return;
   out.remediationHint = hint;
   const total = Math.max(1, compactCount(input.remediationHintCount));
   out.omittedRemediationHintCount = Math.max(0, total - 1);
 }
 
+function decisionRemediation(input: CompactDecisionInput): string | undefined {
+  if (input.remediationCode === 'provide_runtime_variables') {
+    const projection = projectCompactMissingNames(
+      input.missingVariableNames, input.missingVariableCount,
+    );
+    return compactMissingRemediation(projection, 'detailed trace edge');
+  }
+  return input.remediationCode
+    ? compactRemediationHint(input.remediationCode) : undefined;
+}
+
 export function projectCompactDiagnostics(
   values: Array<Record<string, unknown>>,
 ): CompactProjectedDiagnostic[] {
@@ -200,15 +226,6 @@ export function compactStatusTotal(counts: CompactStatusCountsV1): number {
     + counts.ambiguous + counts.unresolved + counts.cycle;
 }
 
-export function removeEquivalentCompactPersistedDecision(
-  decision: CompactDecisionV1,
-): void {
-  if (decision.persistedResolutionStatus !== decision.effectiveResolutionStatus) return;
-  if (!decision.persistedTarget || decision.persistedTarget !== decision.effectiveTarget) return;
-  delete decision.persistedResolutionStatus;
-  delete decision.persistedTarget;
-}
-
 function compactBlockingDiagnostic(item: CompactDiagnosticRowV1): boolean {
   if (item[1] === 'error') return true;
   return item[2] === 'schema_upgrade_required'
@@ -242,9 +259,13 @@ function compactDiagnosticDetails(
   const out: CompactDiagnosticDetailsV1 = {};
   const reasonCode = compactSafeCode(value.reasonCode);
   if (reasonCode) out.reasonCode = reasonCode;
-  addDiagnosticNames(out, value);
+  if (selectorDiagnosticCodes.has(code)) addDiagnosticSelector(out, value);
+  if (code === 'reindex_required') addInvalidFactCategories(out, value);
+  if (code === 'implementation_hint_mismatch')
+    addImplementationHintCandidates(out, value);
+  if (code === 'trace_runtime_variables_missing') addDiagnosticNames(out, value);
   addDiagnosticCounts(out, value);
-  const hint = compactDiagnosticRemediation(code);
+  const hint = compactDiagnosticRemediation(code, out);
   if (hint) {
     out.remediationHint = hint;
     out.omittedHintCount = Math.max(
@@ -254,18 +275,70 @@ function compactDiagnosticDetails(
   return out;
 }
 
+function addDiagnosticSelector(
+  out: CompactDiagnosticDetailsV1,
+  value: Record<string, unknown>,
+): void {
+  const selectorKind = compactSafeCode(value.selectorKind);
+  if (selectorKind) out.selectorKind = selectorKind;
+  const suggestions = projectCompactReferenceGroup(
+    compactStringArray(value.selectorSuggestions),
+    value.selectorSuggestionCount,
+    isSafeCompactSelectorSuggestion,
+  );
+  if (suggestions) out.selectorSuggestions = suggestions;
+}
+
+function addInvalidFactCategories(
+  out: CompactDiagnosticDetailsV1,
+  value: Record<string, unknown>,
+): void {
+  const categories = compactRecordArray(value.invalidFactCategories)
+    .flatMap((item) =>
+      typeof item.category === 'string' ? [item.category] : []);
+  const projection = projectCompactReferenceGroup(
+    categories, value.invalidFactCategoryCount,
+    (item) => compactSafeCode(item) === item,
+  );
+  if (projection) out.invalidFactCategories = projection;
+}
+
+function addImplementationHintCandidates(
+  out: CompactDiagnosticDetailsV1,
+  value: Record<string, unknown>,
+): void {
+  const repos = compactRecordArray(value.implementationHintSuggestions)
+    .flatMap((item) =>
+      typeof item.implementationRepo === 'string'
+        ? [item.implementationRepo] : []);
+  const uniqueCount = new Set(repos.map((repo) => repo.trim())).size;
+  if (uniqueCount < 2) return;
+  const projection = projectCompactReferenceGroup(
+    repos, value.implementationHintSuggestionCount,
+    isSafeCompactReferenceName,
+  );
+  if (projection) out.tiedCandidateRepos = projection;
+}
+
 function addDiagnosticNames(
   out: CompactDiagnosticDetailsV1,
   value: Record<string, unknown>,
 ): void {
-  const allNames = safeVariableNames(compactStringArray(value.missingVariables));
-  const names = allNames.slice(0, compactNameLimit);
-  const total = Math.max(allNames.length, compactCount(value.missingVariableCount));
-  if (names.length > 0) out.missingVariableNames = names;
-  if (total === 0) return;
-  out.missingVariableCount = total;
-  out.shownMissingVariableCount = names.length;
-  out.omittedMissingVariableCount = Math.max(0, total - names.length);
+  const projection = projectCompactMissingNames(
+    compactStringArray(value.missingVariables), value.missingVariableCount,
+  );
+  applyMissingProjection(out, projection);
+}
+
+function applyMissingProjection(
+  out: CompactDecisionV1 | CompactDiagnosticDetailsV1,
+  projection: CompactMissingNameProjection,
+): void {
+  if (projection.names.length > 0) out.missingVariableNames = projection.names;
+  if (projection.total === 0) return;
+  out.missingVariableCount = projection.total;
+  out.shownMissingVariableCount = projection.shown;
+  out.omittedMissingVariableCount = projection.omitted;
 }
 
 function addDiagnosticCounts(
@@ -303,11 +376,19 @@ function compactDiagnosticSeverity(value: unknown): 'error' | 'warning' | 'info'
   return value === 'error' || value === 'warning' ? value : 'info';
 }
 
-function compactDiagnosticRemediation(code: string): string | undefined {
+function compactDiagnosticRemediation(
+  code: string,
+  details: CompactDiagnosticDetailsV1,
+): string | undefined {
   if (code === 'schema_upgrade_required' || code === 'reindex_required')
     return compactRemediationHint('reindex_and_link');
   if (code === 'trace_runtime_variables_missing')
-    return compactRemediationHint('provide_runtime_variables');
+    return compactMissingRemediation({
+      names: details.missingVariableNames ?? [],
+      total: details.missingVariableCount ?? 0,
+      shown: details.shownMissingVariableCount ?? 0,
+      omitted: details.omittedMissingVariableCount ?? 0,
+    }, 'detailed diagnostic');
   if (code === 'implementation_hint_mismatch')
     return compactRemediationHint('select_implementation');
   return undefined;
@@ -329,7 +410,8 @@ function compactDiagnosticHintCount(
 
 function compactRemediationHint(code: string): string | undefined {
   if (code === 'provide_runtime_variables') return 'Provide the missing variable names listed in details.';
-  if (code === 'select_implementation') return 'Select one implementation with a scoped implementation hint.';
+  if (code === 'select_implementation')
+    return 'Use --implementation-hint with service, operation, package, repository, family, and repo keys; repo is required.';
   if (code === 'reindex_and_link') return 'Force reindex, then force relink the workspace.';
   if (code === 'inspect_detailed_edge') return 'Inspect the correlated detailed trace edge.';
   return undefined;
@@ -358,11 +440,6 @@ function compactSafeSourceFile(value: unknown): string | undefined {
     && !/^[a-z]+:\/\//i.test(value) && !/[\r\n]/.test(value) ? value : undefined;
 }
 
-function safeVariableNames(values: string[] | undefined): string[] {
-  return compactSortedUnique((values ?? [])
-    .filter((value) => /^[A-Za-z_$][\w$]*$/.test(value)));
-}
-
 function compactCount(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value)
     ? Math.max(0, Math.floor(value)) : 0;
@@ -378,6 +455,13 @@ function compactStringArray(value: unknown): string[] {
     ? value.filter((item): item is string => typeof item === 'string') : [];
 }
 
+function compactRecordArray(value: unknown): Array<Record<string, unknown>> {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> =>
+        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
+    : [];
+}
+
 function compactArrayLength(value: unknown): number {
   return Array.isArray(value) ? value.length : 0;
 }

package/src/trace/021-compact-decision-normalization.ts

@@ -0,0 +1,171 @@
+import { compareBinary } from './010-traversal-scope.js';
+import type {
+  CompactDecisionV1,
+  CompactReferenceGroupV1,
+  CompactStatus,
+} from './014-compact-contract.js';
+
+export const COMPACT_MISSING_NAME_LIMIT = 8;
+export const COMPACT_MISSING_NAME_MAX_LENGTH = 160;
+export const COMPACT_REFERENCE_VALUE_LIMIT = 5;
+const COMPACT_REFERENCE_VALUE_MAX_LENGTH = 240;
+
+export interface CompactMissingNameProjection {
+  readonly names: string[];
+  readonly total: number;
+  readonly shown: number;
+  readonly omitted: number;
+}
+
+const identifier = '[A-Za-z_$][A-Za-z0-9_$]*';
+const member = `(?:(?:\\.|\\?\\.)${identifier}|(?:\\[|\\?\\.\\[)(?:0|[1-9][0-9]*)\\])`;
+const transform = '(?:(?:\\.|\\?\\.)(?:toLowerCase|toUpperCase|trim)\\(\\))?';
+const safeMissingName = new RegExp(`^${identifier}(?:${member})*${transform}$`);
+
+export function projectCompactMissingNames(
+  values: readonly string[] | undefined,
+  authoritativeCount: unknown,
+): CompactMissingNameProjection {
+  const candidates = new Map<string, boolean>();
+  for (const value of values ?? []) {
+    const normalized = value.trim();
+    if (!normalized) continue;
+    candidates.set(
+      normalized,
+      (candidates.get(normalized) ?? true) && isSafeCompactMissingName(value),
+    );
+  }
+  const raw = [...candidates.keys()].sort(compareBinary);
+  const safe = raw.filter((name) => candidates.get(name) === true);
+  const names = safe.slice(0, COMPACT_MISSING_NAME_LIMIT);
+  const total = Math.max(compactCount(authoritativeCount), raw.length);
+  return {
+    names, total, shown: names.length,
+    omitted: Math.max(0, total - names.length),
+  };
+}
+
+export function isSafeCompactMissingName(value: string): boolean {
+  if (hasControlCharacter(value)) return false;
+  const normalized = value.trim();
+  return normalized.length > 0
+    && normalized.length <= COMPACT_MISSING_NAME_MAX_LENGTH
+    && safeMissingName.test(normalized);
+}
+
+export function projectCompactReferenceGroup(
+  values: readonly string[] | undefined,
+  authoritativeCount: unknown,
+  isSafe: (value: string) => boolean,
+): CompactReferenceGroupV1 | undefined {
+  const candidates = normalizedReferenceValues(values, isSafe);
+  const unique = [...candidates.keys()].sort(compareBinary);
+  const safe = unique.filter((value) => candidates.get(value) === true);
+  const shown = safe.slice(0, COMPACT_REFERENCE_VALUE_LIMIT);
+  const total = Math.max(compactCount(authoritativeCount), unique.length);
+  if (total === 0) return undefined;
+  return {
+    values: shown,
+    total,
+    shown: shown.length,
+    omitted: Math.max(0, total - shown.length),
+  };
+}
+
+export function isSafeCompactReferenceName(value: string): boolean {
+  if (!safeReferenceText(value, 160)) return false;
+  return /^[@A-Za-z0-9_$][@A-Za-z0-9_$./:-]*$/.test(value.trim());
+}
+
+export function isSafeCompactSelectorSuggestion(value: string): boolean {
+  if (!safeReferenceText(value, COMPACT_REFERENCE_VALUE_MAX_LENGTH))
+    return false;
+  return /^(?:--(?:repo|service|operation|path|handler) [@A-Za-z0-9_$./:-]+)(?: --(?:repo|service|operation|path|handler) [@A-Za-z0-9_$./:-]+)*$/
+    .test(value.trim());
+}
+
+export function normalizeCompactDecisionEquivalence(
+  decision: CompactDecisionV1,
+  status: CompactStatus,
+  canonicalTarget: string | undefined,
+  targetIdentityEqual = false,
+  persistedIdentityEqual = false,
+  rawPersistedStatus?: string,
+): void {
+  if (decision.effectiveResolutionStatus === status)
+    delete decision.effectiveResolutionStatus;
+  removeEquivalentPersistedDecision(
+    decision, status, canonicalTarget, persistedIdentityEqual,
+    rawPersistedStatus,
+  );
+  if (targetIdentityEqual && canonicalTarget !== undefined
+    && decision.effectiveTarget === canonicalTarget)
+    delete decision.effectiveTarget;
+}
+
+export function compactMissingRemediation(
+  projection: CompactMissingNameProjection,
+  artifact: 'detailed diagnostic' | 'detailed trace edge',
+): string {
+  if (projection.total > 0 && projection.shown === projection.total)
+    return 'Provide the missing variable names listed in details.';
+  if (projection.shown > 0)
+    return `Provide the listed names; inspect the correlated ${artifact} for omitted names.`;
+  return `Inspect the correlated ${artifact} for missing variable names.`;
+}
+
+function removeEquivalentPersistedDecision(
+  decision: CompactDecisionV1,
+  status: CompactStatus,
+  canonicalTarget: string | undefined,
+  identityEqual: boolean,
+  rawPersistedStatus: string | undefined,
+): void {
+  if (!identityEqual
+    || rawPersistedStatus !== status
+    || (decision.effectiveResolutionStatus !== undefined
+      && decision.persistedResolutionStatus
+        !== decision.effectiveResolutionStatus))
+    return;
+  if (!decision.persistedTarget || canonicalTarget === undefined
+    || decision.persistedTarget !== canonicalTarget)
+    return;
+  delete decision.persistedResolutionStatus;
+  delete decision.persistedTarget;
+}
+
+function compactCount(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.floor(value)) : 0;
+}
+
+function normalizedReferenceValues(
+  values: readonly string[] | undefined,
+  isSafe: (value: string) => boolean,
+): Map<string, boolean> {
+  const unique = new Map<string, boolean>();
+  for (const raw of values ?? []) {
+    const value = raw.trim();
+    if (!value) continue;
+    unique.set(value, (unique.get(value) ?? true) && isSafe(raw));
+  }
+  return unique;
+}
+
+function safeReferenceText(value: string, maxLength: number): boolean {
+  if (hasControlCharacter(value)) return false;
+  const normalized = value.trim();
+  return normalized.length > 0
+    && normalized.length <= maxLength
+    && !/^[a-z]+:\/\//i.test(normalized)
+    && !/(?:^|[^A-Za-z0-9])(?:authorization|bearer|credential|destination|password|secret|token)(?:$|[^A-Za-z0-9])/i
+      .test(normalized);
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127) return true;
+  }
+  return false;
+}

package/src/trace/022-trace-fact-preflight.ts

@@ -0,0 +1,21 @@
+import type { Db } from '../db/connection.js';
+import { currentFactLifecycleDiagnostic } from '../db/001-fact-lifecycle.js';
+import { resolveTraversalWorkspaceId } from './010-traversal-scope.js';
+
+function workspaceScopeIsAmbiguous(db: Db): boolean {
+  const rows = db.prepare(`SELECT DISTINCT workspace_id workspaceId
+    FROM repositories ORDER BY workspace_id LIMIT 2`).all();
+  return rows.length > 1;
+}
+
+export function shouldDeferTraceStartSelection(
+  db: Db,
+  requestedWorkspaceId: number | undefined,
+  repoId: number | undefined,
+): boolean {
+  const workspaceId = resolveTraversalWorkspaceId(
+    db, requestedWorkspaceId, repoId,
+  );
+  if (workspaceId === undefined) return workspaceScopeIsAmbiguous(db);
+  return currentFactLifecycleDiagnostic(db, workspaceId) !== undefined;
+}

package/src/trace/023-nested-event-scopes.ts

@@ -0,0 +1,23 @@
+import type { Db } from '../db/connection.js';
+
+export function outboundScopeSymbolIds(
+  db: Db,
+  symbolIds: ReadonlySet<number> | undefined,
+  includeAsync: boolean,
+): ReadonlySet<number> | undefined {
+  if (!includeAsync || !symbolIds || symbolIds.size === 0) return symbolIds;
+  const ids = [...symbolIds];
+  const rows = db.prepare(`SELECT DISTINCT child.id FROM symbols parent
+    JOIN symbols child ON child.repo_id=parent.repo_id
+      AND child.source_file=parent.source_file
+      AND child.kind='event_registration'
+      AND parent.start_offset<=child.start_offset
+      AND parent.end_offset>=child.end_offset
+    WHERE parent.id IN (${ids.map(() => '?').join(',')})
+    ORDER BY child.id`).all(...ids);
+  return new Set([
+    ...ids,
+    ...rows.flatMap((row) =>
+      typeof row.id === 'number' ? [row.id] : []),
+  ]);
+}

package/src/trace/024-compact-observation-decision.ts

@@ -0,0 +1,81 @@
+import type {
+  CompactDecisionTargetInput,
+  CompactDecisionV1,
+  CompactEdgeObservation,
+} from './014-compact-contract.js';
+import { projectCompactDecision } from './020-compact-field-projection.js';
+import { normalizeCompactDecisionEquivalence } from
+  './021-compact-decision-normalization.js';
+
+export interface CompactDecisionNode {
+  key?: string;
+  decisionTarget?: string;
+  projectedIdentity?: boolean;
+}
+
+function resolvedNode(
+  value: CompactDecisionTargetInput | undefined,
+  resolve: (input: CompactDecisionTargetInput) => CompactDecisionNode,
+): CompactDecisionNode | undefined {
+  return value ? resolve(value) : undefined;
+}
+
+function applyEffectiveTarget(
+  decision: CompactDecisionV1,
+  effective: CompactDecisionNode | undefined,
+): void {
+  if (effective?.decisionTarget)
+    decision.effectiveTarget = effective.decisionTarget;
+}
+
+function applyPersistedTarget(
+  decision: CompactDecisionV1,
+  persisted: CompactDecisionNode | undefined,
+  status: string | undefined,
+): void {
+  if (persisted?.decisionTarget && status)
+    decision.persistedTarget = persisted.decisionTarget;
+}
+
+function sameCanonicalNode(
+  left: CompactDecisionNode | undefined,
+  right: CompactDecisionNode,
+): boolean {
+  if (left?.key === undefined) return false;
+  return left.projectedIdentity === true
+    ? left.key === right.decisionTarget
+    : left.key === right.key;
+}
+
+function persistedCanonical(
+  persisted: CompactDecisionNode | undefined,
+  effective: CompactDecisionNode | undefined,
+  target: CompactDecisionNode,
+): boolean {
+  if (!sameCanonicalNode(persisted, target)) return false;
+  return effective?.key === undefined || sameCanonicalNode(effective, target);
+}
+
+export function projectObservationDecision(
+  input: CompactEdgeObservation,
+  target: CompactDecisionNode,
+  resolve: (value: CompactDecisionTargetInput) => CompactDecisionNode,
+): CompactDecisionV1 {
+  const decision = projectCompactDecision(input.decision);
+  const source = input.decision;
+  const effective = resolvedNode(source?.effectiveTarget, resolve);
+  const persisted = resolvedNode(source?.persistedTarget, resolve);
+  applyEffectiveTarget(decision, effective);
+  applyPersistedTarget(
+    decision, persisted, source?.persistedResolutionStatus,
+  );
+  normalizeCompactDecisionEquivalence(
+    decision,
+    input.status,
+    target.decisionTarget,
+    sameCanonicalNode(effective, target),
+    persistedCanonical(persisted, effective, target),
+    source?.persistedResolutionStatus,
+  );
+  return decision;
+}

package/src/trace/025-trace-implementation-scope.ts

@@ -0,0 +1,123 @@
+import type { Db } from '../db/connection.js';
+import type { ImplementationHint } from '../types.js';
+import type { TraceGraphEdgeRow } from './012-trace-graph-lookups.js';
+
+export interface ImplementationHintOptions {
+  implementationRepo?: string;
+  implementationHints?: ImplementationHint[];
+}
+
+export interface ImplementationScope {
+  repoId?: number;
+  files: Set<string>;
+  symbolId?: number;
+  edge?: TraceGraphEdgeRow;
+}
+
+interface HandlerScopeRow {
+  repoId?: number;
+  sourceFile?: string;
+  symbolId?: number;
+}
+
+function normalizeOperation(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  return value.startsWith('/') ? value.slice(1) : value;
+}
+
+function implementationEdge(
+  db: Db,
+  operationId: string,
+): TraceGraphEdgeRow | undefined {
+  return db.prepare(`SELECT * FROM graph_edges
+    WHERE edge_type='OPERATION_IMPLEMENTED_BY_HANDLER'
+      AND from_kind='operation' AND from_id=?
+    ORDER BY CASE status WHEN 'resolved' THEN 0
+      WHEN 'ambiguous' THEN 1 ELSE 2 END,id LIMIT 1`)
+    .get(operationId) as TraceGraphEdgeRow | undefined;
+}
+
+function handlerScopeRow(db: Db, methodId: string): HandlerScopeRow | undefined {
+  return db.prepare(`SELECT hc.repo_id repoId,hc.source_file sourceFile,
+      s.id symbolId
+    FROM handler_methods hm
+    JOIN handler_classes hc ON hc.id=hm.handler_class_id
+    LEFT JOIN symbols s ON s.repo_id=hc.repo_id
+      AND s.source_file=hc.source_file
+      AND s.qualified_name=hc.class_name || '.' || hm.method_name
+      AND s.start_line=hm.source_line
+    WHERE hm.id=?`).get(methodId) as HandlerScopeRow | undefined;
+}
+
+export function implementationScope(
+  db: Db,
+  operationId: string,
+): ImplementationScope {
+  const edge = implementationEdge(db, operationId);
+  if (!edge || edge.status !== 'resolved') return { files: new Set(), edge };
+  const row = handlerScopeRow(db, edge.to_id);
+  if (!row || typeof row.symbolId !== 'number')
+    return { repoId: row?.repoId, files: new Set(), edge };
+  return {
+    repoId: row.repoId,
+    files: new Set(row.sourceFile ? [row.sourceFile] : []),
+    symbolId: row.symbolId,
+    edge,
+  };
+}
+
+export function handlerScope(
+  db: Db,
+  methodId: string,
+): Omit<ImplementationScope, 'edge'> | undefined {
+  const row = handlerScopeRow(db, methodId);
+  if (!row || typeof row.symbolId !== 'number') return undefined;
+  return {
+    repoId: row.repoId,
+    files: new Set(row.sourceFile ? [row.sourceFile] : []),
+    symbolId: row.symbolId,
+  };
+}
+
+export function handlerFilesForOperation(
+  db: Db,
+  operationId: string,
+): Set<string> {
+  const op = db.prepare(`SELECT o.operation_name operationName,
+      o.operation_path operationPath,s.repo_id repoId
+    FROM cds_operations o JOIN cds_services s ON s.id=o.service_id
+    WHERE o.id=?`).get(operationId) as {
+    operationName?: string;
+    operationPath?: string;
+    repoId?: number;
+  } | undefined;
+  if (!op) return new Set();
+  const operation = normalizeOperation(op.operationPath ?? op.operationName);
+  const rows = handlerFileRows(db, op.repoId, operation, op.operationName);
+  return new Set(rows.flatMap((row) =>
+    typeof row.sourceFile === 'string' ? [row.sourceFile] : []));
+}
+
+function handlerFileRows(
+  db: Db,
+  repoId: number | undefined,
+  operation: string | undefined,
+  operationName: string | undefined,
+): Array<{ sourceFile?: string }> {
+  return db.prepare(`SELECT DISTINCT hc.source_file sourceFile
+    FROM handler_classes hc
+    JOIN handler_methods hm ON hm.handler_class_id=hc.id
+    WHERE hc.repo_id=?
+      AND COALESCE(json_extract(hm.decorator_resolution_json,'$.handlerKind'),
+        CASE WHEN hm.decorator_kind='Event' THEN 'event'
+          WHEN hm.decorator_kind IN ('Action','Func','On') THEN 'operation'
+          ELSE 'unsupported' END)='operation'
+      AND COALESCE(json_extract(hm.decorator_resolution_json,'$.executable'),
+        CASE WHEN hm.decorator_kind IN ('Action','Func','On')
+          THEN 1 ELSE 0 END)=1
+      AND (hm.decorator_value=? OR hm.method_name=?
+        OR hm.decorator_value=?)`)
+    .all(repoId, operation, operation, operationName) as Array<{
+      sourceFile?: string;
+    }>;
+}