@saptools/service-flow 0.1.68 → 0.1.70

package/src/linker/cross-repo-linker.ts

@@ -1,20 +1,10 @@
 import type { Db } from '../db/connection.js';
-import { applyVariables } from './dynamic-edge-resolver.js';
-import { classifyODataPathIntent, normalizeODataOperationInvocationPath } from './odata-path-normalizer.js';
-import { buildRemoteQueryTarget } from './remote-query-target.js';
-import { resolveOperation } from './service-resolver.js';
 import { linkHelperPackages } from './helper-package-linker.js';
-import { externalHttpTarget } from './external-http-target.js';
-import { linkImplementations as linkCanonicalImplementations } from './000-implementation-candidates.js';
-import {
-  ambiguousPathCandidates,
-  linkedCallEvidence,
-  objectJson,
-  objectValue,
-} from './002-call-evidence.js';
-import { linkPackageImportSymbolCalls } from './003-package-import-symbol-resolver.js';
-import { linkEventSubscriptionHandlers } from './004-event-subscription-handler-linker.js';
-import { assertWorkspaceLinkable } from '../db/001-fact-lifecycle.js';
+import { linkImplementations as linkCanonicalImplementations } from './implementation-candidates.js';
+import { linkPackageImportSymbolCalls } from './package-import-symbol-resolver.js';
+import { linkEventSubscriptionHandlers } from './event-subscription-handler-linker.js';
+import { insertCallEdge } from './call-edge-insertion.js';
+import { assertWorkspaceLinkable } from '../db/fact-lifecycle.js';
 export interface LinkWorkspaceResult {
   edgeCount: number;
   unresolvedCount: number;
@@ -43,7 +33,7 @@ export function linkWorkspace(db: Db, workspaceId: number, vars: Record<string,
     db.prepare('DELETE FROM graph_edges WHERE workspace_id=?').run(workspaceId);
     const deps = linkHelperPackages(db, workspaceId, generation);
     const subscriptions = linkEventSubscriptionHandlers(
-      db, workspaceId, generation,
+      db, workspaceId, generation, vars,
     );
     const impl = linkCanonicalImplementations(db, workspaceId, generation);
     const callSummary = linkCalls(db, workspaceId, vars, generation);
@@ -89,156 +79,3 @@ function linkCalls(db: Db, workspaceId: number, vars: Record<string, string>, ge
   }
   return { edgeCount, unresolvedCount, resolvedCount, remoteResolvedCount, localResolvedCount, ambiguousCount, dynamicCount, terminalCount };
 }
-function insertCallEdge(db: Db, workspaceId: number, call: Record<string, unknown>, vars: Record<string, string>, generation: number): { status: string; callType: string } {
-  const callType = String(call.call_type);
-  const rawOp = applyVariables(String(call.operation_path_expr ?? ''), vars);
-  const intent = classifyODataPathIntent(rawOp, call.method as string | undefined);
-  const isEntityQueryIntent = ['entity_query', 'entity_key_read', 'entity_navigation_query'].includes(intent.kind);
-  const resolutionRawOp = callType === 'remote_query' && isEntityQueryIntent ? intent.pathWithoutQuery : rawOp;
-  const normalized = normalizeODataOperationInvocationPath(resolutionRawOp);
-  const op = normalized?.normalizedOperationPath ?? resolutionRawOp;
-  const servicePath = applyVariables((call.servicePathExpr as string | undefined) ?? (call.requireServicePath as string | undefined), vars);
-  const destination = (call.destinationExpr as string | undefined) ?? (call.requireDestination as string | undefined);
-  const isDynamic = Boolean(Number(call.isDynamic ?? 0));
-  const isRemoteEntityCall = callType.startsWith('remote_entity_');
-  const indexedOperationCandidateCount = operationCandidateCount(db, workspaceId, op, intent.topLevelOperationName);
-  const credibleOperationSignal = Boolean(normalized?.wasInvocation) || (Boolean(intent.topLevelOperationNameCandidate) && indexedOperationCandidateCount > 0);
-  const strongEntitySignal = ['entity_media', 'entity_delete', 'entity_key_read', 'entity_navigation_query'].includes(intent.kind) || (intent.kind === 'entity_mutation' && (intent.hasEntityKeyPredicate || intent.hasNavigationSuffix));
-  const operationLikeRemoteEntity = isRemoteEntityCall && Boolean(op) && credibleOperationSignal && (!strongEntitySignal || indexedOperationCandidateCount > 0);
-  const isOperationCall = operationLikeRemoteEntity || ((callType === 'remote_action' || callType === 'local_service_call') || (callType === 'remote_query' && Boolean(op)));
-  const resolution = isOperationCall ? resolveOperation(db, { servicePath, operationPath: op, serviceName: call.local_service_name as string | undefined, repoId: callType === 'local_service_call' ? Number(call.repo_id) : undefined, alias: applyVariables((call.aliasExpr as string | undefined) ?? (call.alias as string | undefined), vars), destination: destination ? applyVariables(destination, vars) : undefined, isDynamic, hasExplicitOverride: Object.keys(vars).length > 0 || callType === 'local_service_call' }, workspaceId) : { status: 'unresolved' as const, candidates: [], reasons: [] };
-  const evidence: Record<string, unknown> = {
-    ...linkedCallEvidence(
-      call,
-      resolution,
-      servicePath,
-      op,
-      destination ? applyVariables(destination, vars) : undefined,
-      normalized,
-      intent,
-    ),
-    indexedOperationCandidateCount,
-    parserCallType: callType,
-    entityOperationPrecedence: operationPrecedence(
-      callType,
-      intent,
-      indexedOperationCandidateCount,
-      Boolean(resolution.target),
-    ),
-  };
-  const pathAnalysis = objectValue(objectJson(call.evidence_json)?.pathAnalysis);
-  if (callType === 'remote_action' && pathAnalysis?.status === 'ambiguous') {
-    const candidatePaths = ambiguousPathCandidates(pathAnalysis);
-    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,
-      'UNRESOLVED_EDGE',
-      'ambiguous',
-      'call',
-      String(call.id),
-      'operation_candidates',
-      candidatePaths.items.join(','),
-      Number(call.confidence ?? 0.5),
-      JSON.stringify({
-        ...evidence,
-        ambiguousOperationPathCandidateCount: candidatePaths.totalCount,
-        shownAmbiguousOperationPathCandidateCount: candidatePaths.shownCount,
-        omittedAmbiguousOperationPathCandidateCount: candidatePaths.omittedCount,
-      }),
-      0,
-      'Ambiguous operation path candidates require explicit disambiguation',
-      generation,
-    );
-    return { status: 'ambiguous', callType };
-  }
-  if (isRemoteEntityCall && (resolution.target || resolution.candidates.length > 0 || resolution.status === 'dynamic')) {
-    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, operationEntityPrecedence: 'indexed_operation_over_parser_entity' }), 0, generation);
-      return { status: 'resolved', callType };
-    }
-    const status = resolution.status === 'dynamic' ? 'dynamic' : resolution.status === 'ambiguous' ? 'ambiguous' : 'unresolved';
-    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, status === 'dynamic' ? 'DYNAMIC_EDGE_CANDIDATE' : 'UNRESOLVED_EDGE', status, 'call', String(call.id), 'operation_candidate', op ? `Remote action: ${op}` : 'Remote action: unknown path', Number(call.confidence ?? 0.2), JSON.stringify({ ...evidence, operationEntityPrecedence: resolution.candidates.length > 0 ? 'parser_entity_with_indexed_operation_candidates' : 'parser_entity_operation_candidate_without_indexed_match' }), status === 'dynamic' ? 1 : 0, unresolvedOperationReason(resolution), generation);
-    return { status, callType };
-  }
-  if (isRemoteEntityCall) {
-    const target = buildRemoteQueryTarget({ queryEntity: intent.entitySegment ?? call.query_entity, servicePath, serviceAlias: call.alias, serviceAliasExpr: call.aliasExpr, destination: destination ? applyVariables(destination, vars) : undefined, isDynamic, parserWarning: evidence.parserWarning });
-    const entityKind = callType;
-    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, 'HANDLER_ACCESSES_REMOTE_ENTITY', 'terminal', 'call', String(call.id), target.toKind, target.toId, Number(call.confidence ?? 0.5), JSON.stringify({ ...evidence, ...target.evidence, remoteEntityAccess: entityKind }), 0, generation);
-    return { status: 'terminal', callType };
-  }
-  if (callType === 'remote_query' && (isEntityQueryIntent || !op) && !resolution.target) {
-    const target = buildRemoteQueryTarget({ queryEntity: call.query_entity, servicePath, serviceAlias: call.alias, serviceAliasExpr: call.aliasExpr, destination: destination ? applyVariables(destination, vars) : undefined, isDynamic, parserWarning: evidence.parserWarning });
-    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, 'HANDLER_RUNS_REMOTE_QUERY', 'terminal', 'call', String(call.id), target.toKind, target.toId, Number(call.confidence ?? 0.5), JSON.stringify({ ...evidence, ...target.evidence }), 0, generation);
-    return { status: 'terminal', callType };
-  }
-  if (callType === 'local_service_call' && call.unresolved_reason === 'transport_client_method' && !resolution.target && resolution.candidates.length === 0) {
-    db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, 'HANDLER_CALLS_TRANSPORT_METHOD', 'terminal', 'call', String(call.id), 'transport_method', String(op || 'transport_client_method'), Number(call.confidence ?? 0.5), JSON.stringify({ ...evidence, classification: 'transport_client_method' }), 0, generation);
-    return { status: 'terminal', callType };
-  }
-  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, callType === 'local_service_call' ? 'LOCAL_CALL_RESOLVES_TO_OPERATION' : 'REMOTE_CALL_RESOLVES_TO_OPERATION', 'resolved', 'call', String(call.id), 'operation', String(resolution.target.operationId), resolution.target.score, JSON.stringify(evidence), 0, generation);
-    return { status: 'resolved', callType };
-  }
-  const edgeType = callType === 'local_db_query' ? 'HANDLER_RUNS_DB_QUERY' : callType === 'external_http' ? 'HANDLER_CALLS_EXTERNAL_HTTP' : callType === 'async_emit' ? 'HANDLER_EMITS_EVENT' : callType === 'async_subscribe' ? 'EVENT_CONSUMED_BY_HANDLER' : resolution.status === 'dynamic' ? 'DYNAMIC_EDGE_CANDIDATE' : 'UNRESOLVED_EDGE';
-  const status = edgeType === 'DYNAMIC_EDGE_CANDIDATE' ? 'dynamic' : resolution.status === 'ambiguous' ? 'ambiguous' : edgeType === 'UNRESOLVED_EDGE' ? 'unresolved' : 'terminal';
-  const unresolvedReason = status === 'terminal' ? null : String(call.unresolved_reason ?? unresolvedOperationReason(resolution));
-  const externalTarget = callType === 'external_http' ? externalHttpTarget(call) : undefined;
-  const targetKind = callType === 'local_db_query' ? 'db_entity' : callType.startsWith('async_') ? 'event' : callType === 'external_http' ? (externalTarget?.toKind ?? 'external_endpoint') : 'operation_candidate';
-  const targetId = callType === 'local_db_query' ? String(call.query_entity ?? 'unknown') : callType === 'remote_action' ? (op ? `Remote action: ${op}` : (call.unresolved_reason === 'dynamic_operation_path_identifier' ? 'Remote action: dynamic path' : 'Remote action: unknown path')) : callType === 'external_http' ? String(externalTarget?.toId ?? 'unknown') : String(call.event_name_expr ?? op ?? 'unknown');
-  const graphLevelDynamic = edgeType === 'DYNAMIC_EDGE_CANDIDATE' && resolution.status === 'dynamic';
-  const finalEvidence = externalTarget ? { ...evidence, externalTarget } : evidence;
-  db.prepare('INSERT INTO graph_edges(workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,confidence,evidence_json,is_dynamic,unresolved_reason,generation) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)').run(workspaceId, edgeType, status, 'call', String(call.id), targetKind, targetId, Number(call.confidence ?? 0.2), JSON.stringify(finalEvidence), graphLevelDynamic ? 1 : 0, unresolvedReason, generation);
-  return { status, callType };
-}
-function operationCandidateCount(db: Db, workspaceId: number, operationPath: string | undefined, operationName: string | undefined): number {
-  if (!operationPath && !operationName) return 0;
-  const normalizedName = operationName ?? operationPath?.replace(/^\//, '').split('.').at(-1);
-  const row = db.prepare(`SELECT COUNT(*) count 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=? AND (o.operation_path=? OR o.operation_path=? OR o.operation_name=?)`).get(workspaceId, operationPath, normalizedName ? `/${normalizedName}` : operationPath, normalizedName) as { count?: number } | undefined;
-  return Number(row?.count ?? 0);
-}
-
-function operationPrecedence(
-  callType: string,
-  intent: ReturnType<typeof classifyODataPathIntent>,
-  indexedOperationCandidateCount: number,
-  resolvedOperation: boolean,
-): Record<string, unknown> {
-  if (resolvedOperation) {
-    return {
-      decision: 'operation',
-      reason: 'indexed_operation_with_strong_service_context',
-      indexedOperationCandidateCount,
-    };
-  }
-  if (callType === 'remote_action' && intent.kind === 'operation_invocation') {
-    return {
-      decision: 'operation_candidate',
-      rejectionReason: indexedOperationCandidateCount > 0
-        ? 'indexed_candidates_lack_unique_strong_service_context'
-        : 'no_indexed_operation_candidate',
-      indexedOperationCandidateCount,
-    };
-  }
-  if (intent.kind.startsWith('entity_')) {
-    return {
-      decision: 'entity',
-      rejectionReason: indexedOperationCandidateCount > 0
-        ? 'entity_shape_has_precedence_without_resolved_operation_context'
-        : 'entity_shape_has_no_indexed_operation_evidence',
-      indexedOperationCandidateCount,
-    };
-  }
-  return {
-    decision: 'unresolved',
-    rejectionReason: 'path_has_no_safe_entity_or_operation_precedence',
-    indexedOperationCandidateCount,
-  };
-}
-
-function unresolvedOperationReason(resolution: { candidates: unknown[]; status: string; reasons: string[] }): string {
-  if (resolution.status === 'dynamic') return `Dynamic target requires runtime variable overrides: ${(resolution.reasons.length ? resolution.reasons : ['missing runtime variables']).join(', ')}`;
-  if (resolution.candidates.length === 0) return 'No indexed target operation matched';
-  if (resolution.reasons.includes('operation_path_only_has_no_strong_target_signal')) return 'Operation candidates found but no strong service signal is available';
-  if (resolution.reasons.includes('candidate_score_below_resolution_threshold')) return 'Operation candidates found but resolution score is below threshold';
-  if (resolution.status === 'ambiguous') return 'Ambiguous operation candidates require a strong service signal';
-  return 'Operation candidates found but resolution could not select a target';
-}

package/src/linker/dynamic-edge-resolver.ts

@@ -1,4 +1,4 @@
-import { extractPlaceholderKeys, scanPlaceholders } from '../utils/001-placeholders.js';
+import { extractPlaceholderKeys, scanPlaceholders } from '../utils/placeholders.js';
 
 export interface RuntimeSubstitution {
   original?: string;

package/src/linker/{004-event-subscription-handler-linker.ts → event-subscription-handler-linker.ts}

@@ -1,4 +1,8 @@
 import type { Db } from '../db/connection.js';
+import {
+  linkEventTemplate,
+  type LinkedEventTemplate,
+} from './event-template-link.js';
 
 export interface SubscriptionHandlerLinkSummary {
   edgeCount: number;
@@ -20,6 +24,7 @@ interface SubscriptionRow {
   startOffset?: number | null;
   endOffset?: number | null;
   confidence: number;
+  unresolvedReason?: string | null;
 }
 
 interface HandlerCallRow {
@@ -58,7 +63,7 @@ function subscriptionRows(db: Db, workspaceId: number): SubscriptionRow[] {
     c.source_symbol_id sourceSymbolId,c.event_name_expr eventName,
     c.source_file sourceFile,c.source_line sourceLine,
     c.call_site_start_offset startOffset,c.call_site_end_offset endOffset,
-    c.confidence
+    c.confidence,c.unresolved_reason unresolvedReason
     FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
     WHERE r.workspace_id=? AND c.call_type='async_subscribe'
       AND json_extract(c.evidence_json,'$.handlerReferenceStatus')
@@ -202,11 +207,16 @@ function missingAssociation(
 function evidenceFor(
   subscription: SubscriptionRow,
   association: HandlerAssociation,
+  event: LinkedEventTemplate,
 ): Record<string, unknown> {
   const call: Partial<HandlerCallRow> = association.call ?? {};
   const symbolCallReason = boundedSymbolCallReason(call.unresolvedReason);
   return {
     eventName: subscription.eventName,
+    ...(event.substitution.placeholders.length > 0 ? {
+      effectiveEventName: event.targetId,
+      eventTemplateResolution: event.substitution,
+    } : {}),
     associationBasis: 'exact_subscription_call_span',
     dispatchScope: 'workspace_event_name_only',
     subscribeCallId: subscription.id,
@@ -253,22 +263,27 @@ function insertAssociationEdge(
   generation: number,
   subscription: SubscriptionRow,
   association: HandlerAssociation,
+  event: LinkedEventTemplate,
 ): void {
+  const status = event.isDynamic ? 'unresolved' : association.status;
+  const reason = event.isDynamic
+    ? 'event_template_variables_missing'
+    : association.reasonCode ?? association.call?.unresolvedReason ?? null;
   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,
     'EVENT_SUBSCRIPTION_HANDLED_BY',
-    association.status,
-    'event',
-    subscription.eventName,
+    status,
+    event.targetKind,
+    event.targetId,
     association.toKind,
     association.toId,
     association.call?.confidence ?? subscription.confidence,
-    JSON.stringify(evidenceFor(subscription, association)),
-    0,
-    association.reasonCode ?? association.call?.unresolvedReason ?? null,
+    JSON.stringify(evidenceFor(subscription, association, event)),
+    event.isDynamic ? 1 : 0,
+    reason,
     generation,
   );
 }
@@ -277,6 +292,7 @@ export function linkEventSubscriptionHandlers(
   db: Db,
   workspaceId: number,
   generation: number,
+  variables: Record<string, string> = {},
 ): SubscriptionHandlerLinkSummary {
   const summary: SubscriptionHandlerLinkSummary = {
     edgeCount: 0,
@@ -286,16 +302,21 @@ export function linkEventSubscriptionHandlers(
     missingAssociationCount: 0,
   };
   for (const subscription of subscriptionRows(db, workspaceId)) {
+    const event = linkEventTemplate(
+      subscription.eventName, variables,
+      subscription.unresolvedReason ?? undefined,
+    );
     const association = associationFor(
       subscription, roleSiteRows(db, subscription),
     );
     insertAssociationEdge(
-      db, workspaceId, generation, subscription, association,
+      db, workspaceId, generation, subscription, association, event,
     );
+    const status = event.isDynamic ? 'unresolved' : association.status;
     summary.edgeCount += 1;
-    summary.resolvedCount += association.status === 'resolved' ? 1 : 0;
-    summary.ambiguousCount += association.status === 'ambiguous' ? 1 : 0;
-    summary.unresolvedCount += association.status === 'unresolved' ? 1 : 0;
+    summary.resolvedCount += status === 'resolved' ? 1 : 0;
+    summary.ambiguousCount += status === 'ambiguous' ? 1 : 0;
+    summary.unresolvedCount += status === 'unresolved' ? 1 : 0;
     summary.missingAssociationCount += association.missing ? 1 : 0;
   }
   return summary;

package/src/linker/event-template-link.ts

@@ -0,0 +1,72 @@
+import type { Db } from '../db/connection.js';
+import {
+  substituteVariables,
+  type RuntimeSubstitution,
+} from './dynamic-edge-resolver.js';
+
+export interface LinkedEventTemplate {
+  targetId: string;
+  targetKind: 'event' | 'event_candidate';
+  status: 'terminal' | 'dynamic';
+  isDynamic: boolean;
+  unresolvedReason?: string;
+  substitution: RuntimeSubstitution;
+}
+
+export function linkEventTemplate(
+  template: string,
+  variables: Record<string, string>,
+  parserReason?: string,
+): LinkedEventTemplate {
+  const substitution = substituteVariables(template, variables);
+  const missing = substitution.missing.length > 0;
+  const unsupportedDynamic = substitution.placeholders.length === 0
+    && parserReason !== undefined;
+  const dynamic = missing || unsupportedDynamic;
+  return {
+    targetId: dynamic
+      ? `Event: ${substitution.effective ?? template}`
+      : substitution.effective ?? template,
+    targetKind: dynamic ? 'event_candidate' : 'event',
+    status: dynamic ? 'dynamic' : 'terminal',
+    isDynamic: dynamic,
+    unresolvedReason: missing
+      ? `Dynamic target requires runtime variable overrides: ${
+          substitution.missing.join(', ')}`
+      : unsupportedDynamic ? parserReason : undefined,
+    substitution,
+  };
+}
+
+export function insertEventCallEdge(
+  db: Db,
+  workspaceId: number,
+  generation: number,
+  call: Record<string, unknown>,
+  variables: Record<string, string>,
+  evidence: Record<string, unknown>,
+): { status: string; callType: string } {
+  const callType = String(call.call_type);
+  const event = linkEventTemplate(
+    String(call.event_name_expr ?? ''), variables,
+    typeof call.unresolved_reason === 'string'
+      ? call.unresolved_reason : undefined,
+  );
+  const edgeType = event.isDynamic
+    ? 'DYNAMIC_EDGE_CANDIDATE'
+    : callType === 'async_emit'
+      ? 'HANDLER_EMITS_EVENT' : 'EVENT_CONSUMED_BY_HANDLER';
+  const eventEvidence = event.substitution.placeholders.length > 0
+    ? { ...evidence, eventTemplateResolution: event.substitution }
+    : evidence;
+  db.prepare(`INSERT INTO graph_edges(
+    workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,
+    confidence,evidence_json,is_dynamic,unresolved_reason,generation
+  ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`).run(
+    workspaceId, edgeType, event.status, 'call', String(call.id),
+    event.targetKind, event.targetId, Number(call.confidence ?? 0.2),
+    JSON.stringify(eventEvidence), event.isDynamic ? 1 : 0,
+    event.unresolvedReason ?? null, generation,
+  );
+  return { status: event.status, callType };
+}

package/src/linker/external-http-target.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { projectBounded } from '../utils/000-bounded-projection.js';
+import { projectBounded } from '../utils/bounded-projection.js';
 
 export type ExternalTargetKind = 'destination' | 'static_url' | 'url_expression' | 'unknown';
 export interface ExternalHttpTarget { kind: ExternalTargetKind; toKind: 'external_destination' | 'external_endpoint'; toId: string; label: string; method?: string; dynamic: boolean; expression?: string; candidateLiteralCount?: number; shownCandidateLiteralCount?: number; omittedCandidateLiteralCount?: number; }

package/src/linker/helper-package-linker.ts

@@ -1,5 +1,5 @@
 import type { Db } from '../db/connection.js';
-import { projectBounded } from '../utils/000-bounded-projection.js';
+import { projectBounded } from '../utils/bounded-projection.js';
 
 interface RepoDependencyRow {
   id: number;

package/src/linker/{000-implementation-candidates.ts → implementation-candidates.ts}

@@ -6,7 +6,7 @@ import {
   boundedImplementationTargetIds,
   displayImplementationCandidates,
   selectedHandlerProvenance,
-} from './001-implementation-evidence-projection.js';
+} from './implementation-evidence-projection.js';
 
 interface ImplementationCandidate extends Record<string, unknown> {
   methodId: number;

package/src/linker/{001-implementation-evidence-projection.ts → implementation-evidence-projection.ts}

@@ -2,7 +2,7 @@ import {
   projectBounded,
   projectBoundedInOrder,
   type BoundedProjection,
-} from '../utils/000-bounded-projection.js';
+} from '../utils/bounded-projection.js';
 
 export interface SelectedHandlerSource {
   methodId: number;

package/src/linker/odata-path-normalizer.ts

@@ -1,7 +1,7 @@
 import {
   analyzeODataPathStructure,
   type ODataPathStructure,
-} from './005-odata-path-structure.js';
+} from './odata-path-structure.js';
 
 export interface NormalizedODataOperationPath {
   rawOperationPath: string;

package/src/linker/{005-odata-path-structure.ts → odata-path-structure.ts}

@@ -1,7 +1,7 @@
 import {
   scanPlaceholderStructure,
   type PlaceholderSpan,
-} from '../utils/001-placeholders.js';
+} from '../utils/placeholders.js';
 
 export type ODataPathStructureReason =
   | 'path_parenthesis_is_unbalanced'

package/src/linker/{003-package-import-symbol-resolver.ts → package-import-symbol-resolver.ts}

@@ -3,14 +3,14 @@ import type {
   PackagePublicScope,
   PackagePublicSurfaceFact,
   PublicSurfaceTarget,
-} from '../parsers/003-package-public-surface.js';
+} from '../parsers/package-public-surface.js';
 import type {
   SymbolImportReference,
-} from '../parsers/002-symbol-import-bindings.js';
+} from '../parsers/symbol-import-bindings.js';
 import {
   parsePackageImportReference,
   parsePackagePublicSurfaceFact,
-} from '../parsers/012-package-fact-contract.js';
+} from '../parsers/package-fact-contract.js';
 
 export interface PackageSymbolLinkSummary {
   resolved: number;

package/src/linker/service-resolver.ts

@@ -1,6 +1,6 @@
 import type { Db } from '../db/connection.js';
-import { extractPlaceholderKeys } from '../utils/001-placeholders.js';
-import { canonicalImplementationEvidence } from './000-implementation-candidates.js';
+import { extractPlaceholderKeys } from '../utils/placeholders.js';
+import { canonicalImplementationEvidence } from './implementation-candidates.js';
 export interface OperationTarget {
   operationId: number;
   repoName: string;

package/src/output/{001-compact-json-output.ts → compact-json-output.ts}

@@ -1,4 +1,4 @@
-import type { CompactGraphV1 } from '../trace/014-compact-contract.js';
+import type { CompactGraphV1 } from '../trace/compact-contract.js';
 import { redactValue } from '../utils/redaction.js';
 
 export function renderCompactJson(value: CompactGraphV1): string {

package/src/parsers/{006-binding-identity.ts → binding-identity.ts}

@@ -9,7 +9,7 @@ import type {
 import {
   executableSymbolCandidates,
   selectCallOwner,
-} from './004-fact-identity.js';
+} from './fact-identity.js';
 import {
   bindingSite,
   createBindingLexicalIndex,
@@ -17,8 +17,8 @@ import {
   type BindingLexicalIndex,
   type BindingLexicalSite,
   type VisibleBinding,
-} from './011-binding-lexical-scope.js';
-import { selectVisibleBinding } from './021-binding-visibility.js';
+} from './binding-lexical-scope.js';
+import { selectVisibleBinding } from './binding-visibility.js';
 
 const scopeChainCap = 16;
 
@@ -230,6 +230,9 @@ function resolvedReference(
   chain: LexicalScopeFact[],
   scopeIndex: number,
 ): ServiceBindingReference {
+  const helperReturn = selected.fact.helperChain?.some(
+    (step) => step.bindingOrigin === 'single_hop_helper_return',
+  ) ?? false;
   return {
     status: 'resolved_exact',
     variableName: call.serviceVariableName,
@@ -240,7 +243,9 @@ function resolvedReference(
       ? 'deterministic_reaching_assignment'
       : selected.site.aliasSource
         ? 'lexical_alias_declaration'
-        : 'lexical_declaration',
+        : helperReturn
+          ? 'single_hop_helper_return'
+          : 'lexical_declaration',
     lexicalScopeChain: chain,
     bindingScopeIndex: scopeIndex,
     scopeChainTotal: chain.length,

package/src/parsers/{011-binding-lexical-scope.ts → binding-lexical-scope.ts}

@@ -3,7 +3,7 @@ import type { LexicalScopeFact } from '../types.js';
 import {
   bindingAssignmentEntries,
   type BindingAssignmentEntry,
-} from './019-binding-assignment-targets.js';
+} from './binding-assignment-targets.js';
 
 export type BindingDeclarationKind =
   | 'const'

package/src/parsers/{021-binding-visibility.ts → binding-visibility.ts}

@@ -10,7 +10,7 @@ import {
   type BindingLexicalSite,
   type BindingSiteCandidate,
   type VisibleBinding,
-} from './011-binding-lexical-scope.js';
+} from './binding-lexical-scope.js';
 
 function reachingSites(
   index: BindingLexicalIndex,
@@ -72,6 +72,20 @@ function candidatesAtSite<T>(
     && candidate.bindingSiteEndOffset === site.endOffset);
 }
 
+function helperCallDeclaration(site: BindingLexicalSite): boolean {
+  if (!ts.isVariableDeclaration(site.node) || !site.node.initializer)
+    return false;
+  let expression = site.node.initializer;
+  while (ts.isAwaitExpression(expression)
+    || ts.isParenthesizedExpression(expression)
+    || ts.isAsExpression(expression)
+    || ts.isSatisfiesExpression(expression)
+    || ts.isTypeAssertionExpression(expression))
+    expression = expression.expression;
+  return ts.isCallExpression(expression)
+    && ts.isIdentifier(expression.expression);
+}
+
 function compatibleCaseClause(
   site: BindingLexicalSite,
   useNode: ts.Node,
@@ -108,7 +122,9 @@ function matchedBinding<T>(
     status: 'unresolved',
     reason: site.flow === 'assignment'
       ? 'unsupported_reaching_assignment'
-      : 'binding_not_found',
+      : helperCallDeclaration(site)
+        ? 'binding_flow_unsupported'
+        : 'binding_not_found',
   };
   if (matches.length > 1) return { status: 'ambiguous' };
   return matches[0] ? { status: 'resolved', candidate: matches[0] } : undefined;

package/src/parsers/{000-direct-query-execution.ts → direct-query-execution.ts}

@@ -43,6 +43,17 @@ export function queryBuilderRoot(
     : undefined;
 }
 
+export function chainIncludesForUpdate(node: ts.Expression): boolean {
+  let current = unwrapQueryExpression(node);
+  while (ts.isCallExpression(current)
+    && ts.isPropertyAccessExpression(current.expression)) {
+    if (isCapQueryBuilderRootName(expressionName(current.expression))) break;
+    if (current.expression.name.text === 'forUpdate') return true;
+    current = unwrapQueryExpression(current.expression.expression);
+  }
+  return false;
+}
+
 export function directQueryBuilderStatement(
   node: ts.CallExpression,
 ): DirectQueryBuilderStatement | undefined {

package/src/parsers/{005-event-subscription-facts.ts → event-subscription-facts.ts}

@@ -9,12 +9,12 @@ import {
   symbolImportReference,
   type SymbolImportBinding,
   type SymbolImportReference,
-} from './002-symbol-import-bindings.js';
+} from './symbol-import-bindings.js';
 import type { ClassifiedOutboundCall } from './outbound-call-parser.js';
 import {
   localSymbolTarget,
   type LocalSymbolTargetIdentity,
-} from './016-local-symbol-reference.js';
+} from './local-symbol-reference.js';
 
 interface HandlerTarget {
   calleeExpression: string;

package/src/parsers/{016-local-symbol-reference.ts → local-symbol-reference.ts}

@@ -3,8 +3,8 @@ import type { ExecutableSymbolFact } from '../types.js';
 import {
   lexicalIdentifierDeclaration,
   lexicalIdentifierDeclarations,
-} from './002-symbol-import-bindings.js';
-import { stableLocalValueReference } from './020-stable-local-value.js';
+} from './symbol-import-bindings.js';
+import { stableLocalValueReference } from './stable-local-value.js';
 
 export interface LocalSymbolTargetIdentity {
   sourceFile: string;

package/src/parsers/operation-path-analysis.ts

@@ -3,7 +3,7 @@ import {
   classifyODataPathIntent,
   normalizeODataOperationInvocationPath,
 } from '../linker/odata-path-normalizer.js';
-import { analyzeODataPathStructure } from '../linker/005-odata-path-structure.js';
+import { analyzeODataPathStructure } from '../linker/odata-path-structure.js';
 
 export type OperationPathStatus = 'static' | 'ambiguous' | 'dynamic' | 'unknown';