@saptools/service-flow 0.1.70 → 0.1.73

package/src/linker/event-shape-candidate-linker.ts

@@ -0,0 +1,204 @@
+import type { Db } from '../db/connection.js';
+import { parseEventSkeletonFact } from '../utils/event-skeleton.js';
+import { boundCandidateLikeEvidence } from '../utils/bounded-projection.js';
+
+export interface EventShapeCandidateLinkSummary {
+  edgeCount: number;
+  omittedCount: number;
+}
+
+const EVENT_SHAPE_LINK_CAP_PER_EMIT = 100;
+
+interface EventShapeRow extends Record<string, unknown> {
+  id: number;
+  repoId: number;
+  repoName: string;
+  signature: string;
+  skeletonJson: string;
+  evidenceJson: string;
+}
+
+interface SubscriberAssociation extends Record<string, unknown> {
+  graphEdgeId: number;
+  subscribeCallId: number;
+  targetKind: string;
+  targetId: string;
+  status: string;
+  evidenceJson: string;
+  targetLabel?: string | null;
+}
+
+function eventRows(
+  db: Db,
+  workspaceId: number,
+  callType: 'async_emit' | 'async_subscribe',
+): EventShapeRow[] {
+  return db.prepare(`SELECT c.id,c.repo_id repoId,r.name repoName,
+    c.event_skeleton_signature signature,
+    c.event_skeleton_json skeletonJson,c.evidence_json evidenceJson
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE r.workspace_id=? AND c.call_type=?
+      AND c.event_skeleton_signature IS NOT NULL
+      AND c.event_skeleton_json IS NOT NULL
+    ORDER BY c.event_skeleton_signature COLLATE BINARY,
+      r.name COLLATE BINARY,r.id,c.source_file COLLATE BINARY,
+      c.call_site_start_offset,c.call_site_end_offset,c.id`).all(
+    workspaceId, callType,
+  ) as unknown as EventShapeRow[];
+}
+
+function associations(
+  db: Db,
+  workspaceId: number,
+  generation: number,
+): SubscriberAssociation[] {
+  return db.prepare(`SELECT edge.id graphEdgeId,
+    CAST(json_extract(edge.evidence_json,'$.subscribeCallId') AS INTEGER)
+      subscribeCallId,
+    edge.to_kind targetKind,edge.to_id targetId,edge.status,
+    edge.evidence_json evidenceJson,
+    target.source_file || ':' || target.qualified_name targetLabel
+    FROM graph_edges edge
+    LEFT JOIN symbols target ON edge.to_kind='symbol'
+      AND target.id=CAST(edge.to_id AS INTEGER)
+    WHERE edge.workspace_id=? AND edge.generation=?
+      AND edge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND edge.to_kind='symbol'
+    ORDER BY subscribeCallId,edge.id`).all(
+    workspaceId, generation,
+  ) as unknown as SubscriberAssociation[];
+}
+
+function parsedEvidence(value: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+function candidateEligible(
+  emit: EventShapeRow,
+  subscribe: EventShapeRow,
+): boolean {
+  if (emit.signature !== subscribe.signature) return false;
+  const left = parseEventSkeletonFact(emit.skeletonJson);
+  const right = parseEventSkeletonFact(subscribe.skeletonJson);
+  return Boolean(left?.candidateEligible && right?.candidateEligible
+    && left.holeCount === right.holeCount
+    && JSON.stringify(left.literalSpans) === JSON.stringify(right.literalSpans));
+}
+
+function candidateEvidence(
+  emit: EventShapeRow,
+  subscribe: EventShapeRow,
+  association: SubscriberAssociation,
+  total: number,
+  shown: number,
+): Record<string, unknown> {
+  const evidence = parsedEvidence(association.evidenceJson);
+  const parser = parsedEvidence(emit.evidenceJson);
+  return {
+    publishCallId: emit.id,
+    subscribeCallId: subscribe.id,
+    eventSkeletonSignature: emit.signature,
+    dispatchScope: 'workspace_event_name_only',
+    dispatchCertainty: 'skeleton_equivalent',
+    subscriptionRepositoryId: subscribe.repoId,
+    subscriptionRepositoryName: subscribe.repoName,
+    subscriptionConsumerRepositoryId:
+      evidence.subscriptionConsumerRepositoryId,
+    subscriptionConsumerRepositoryName:
+      evidence.subscriptionConsumerRepositoryName,
+    handlerSymbolId: Number(association.targetId),
+    eventShapeCandidateTargetLabel: association.targetLabel,
+    associationGraphEdgeId: association.graphEdgeId,
+    outboundEvidence: boundCandidateLikeEvidence(parser),
+    eventShapeLinkCandidateCount: total,
+    shownEventShapeLinkCandidateCount: shown,
+    omittedEventShapeLinkCandidateCount: Math.max(0, total - shown),
+  };
+}
+
+function insertCandidate(
+  db: Db,
+  workspaceId: number,
+  generation: number,
+  emit: EventShapeRow,
+  subscribe: EventShapeRow,
+  association: SubscriberAssociation,
+  total: number,
+  shown: number,
+): void {
+  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_SHAPE_CANDIDATE_SUBSCRIBER',
+    'dynamic',
+    'call',
+    String(emit.id),
+    association.targetKind,
+    association.targetId,
+    0.3,
+    JSON.stringify(candidateEvidence(
+      emit, subscribe, association, total, shown,
+    )),
+    1,
+    'event_skeleton_equivalent_non_authoritative',
+    generation,
+  );
+}
+
+interface ShapeCandidate {
+  subscription: EventShapeRow;
+  association: SubscriberAssociation;
+}
+
+function candidatesForEmit(
+  emit: EventShapeRow,
+  subscriptions: readonly EventShapeRow[],
+  bySubscription: ReadonlyMap<number, SubscriberAssociation[]>,
+): ShapeCandidate[] {
+  return subscriptions.flatMap((subscription) =>
+    !candidateEligible(emit, subscription) ? []
+      : (bySubscription.get(subscription.id) ?? []).map((association) => ({
+          subscription,
+          association,
+        })));
+}
+
+export function linkEventShapeCandidates(
+  db: Db,
+  workspaceId: number,
+  generation: number,
+): EventShapeCandidateLinkSummary {
+  const emits = eventRows(db, workspaceId, 'async_emit');
+  const subscriptions = eventRows(db, workspaceId, 'async_subscribe');
+  const bySubscription = new Map<number, SubscriberAssociation[]>();
+  for (const association of associations(db, workspaceId, generation))
+    bySubscription.set(association.subscribeCallId, [
+      ...(bySubscription.get(association.subscribeCallId) ?? []),
+      association,
+    ]);
+  let edgeCount = 0;
+  let omittedCount = 0;
+  for (const emit of emits) {
+    const candidates = candidatesForEmit(
+      emit, subscriptions, bySubscription,
+    );
+    const shown = candidates.slice(0, EVENT_SHAPE_LINK_CAP_PER_EMIT);
+    for (const candidate of shown) {
+      insertCandidate(
+        db, workspaceId, generation, emit, candidate.subscription,
+        candidate.association, candidates.length, shown.length,
+      );
+      edgeCount += 1;
+    }
+    omittedCount += Math.max(0, candidates.length - shown.length);
+  }
+  return { edgeCount, omittedCount };
+}

package/src/linker/event-subscription-handler-linker.ts

@@ -3,6 +3,11 @@ import {
   linkEventTemplate,
   type LinkedEventTemplate,
 } from './event-template-link.js';
+import {
+  subscriptionEnvironmentTargets,
+  type SubscriptionEnvironmentTarget,
+} from './event-environment-link.js';
+import { parseEventSkeletonFact } from '../utils/event-skeleton.js';
 
 export interface SubscriptionHandlerLinkSummary {
   edgeCount: number;
@@ -25,6 +30,10 @@ interface SubscriptionRow {
   endOffset?: number | null;
   confidence: number;
   unresolvedReason?: string | null;
+  packageName?: string | null;
+  environmentJson?: string | null;
+  eventSkeletonJson?: string | null;
+  evidenceJson?: string | null;
 }
 
 interface HandlerCallRow {
@@ -63,7 +72,11 @@ 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.unresolved_reason unresolvedReason
+    c.confidence,c.unresolved_reason unresolvedReason,
+    c.event_skeleton_json eventSkeletonJson,
+    c.evidence_json evidenceJson,
+    r.package_name packageName,
+    r.environment_declarations_json environmentJson
     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')
@@ -208,11 +221,36 @@ function evidenceFor(
   subscription: SubscriptionRow,
   association: HandlerAssociation,
   event: LinkedEventTemplate,
+  environment?: SubscriptionEnvironmentTarget,
+  loopValue?: string,
 ): Record<string, unknown> {
   const call: Partial<HandlerCallRow> = association.call ?? {};
   const symbolCallReason = boundedSymbolCallReason(call.unresolvedReason);
+  const environmentAmbiguous = environment?.resolution.status === 'ambiguous'
+    || Number(environment?.collisionCount ?? 1) > 1;
+  const resolutionStatus = event.isDynamic
+    ? 'unresolved'
+    : environmentAmbiguous ? 'ambiguous' : association.status;
+  return {
+    ...eventDispatchEvidence(subscription, event, environment, loopValue),
+    ...handlerAssociationEvidence(
+      subscription, association, call, resolutionStatus,
+      environmentAmbiguous, environment,
+    ),
+    ...symbolCallReason,
+  };
+}
+
+function eventDispatchEvidence(
+  subscription: SubscriptionRow,
+  event: LinkedEventTemplate,
+  environment?: SubscriptionEnvironmentTarget,
+  loopValue?: string,
+): Record<string, unknown> {
   return {
     eventName: subscription.eventName,
+    materializedLoopEventName: loopValue,
+    ...(eventSkeletonEvidence(subscription.eventSkeletonJson)),
     ...(event.substitution.placeholders.length > 0 ? {
       effectiveEventName: event.targetId,
       eventTemplateResolution: event.substitution,
@@ -220,12 +258,37 @@ function evidenceFor(
     associationBasis: 'exact_subscription_call_span',
     dispatchScope: 'workspace_event_name_only',
     subscribeCallId: subscription.id,
+    repositoryId: subscription.repoId,
+    repositoryName: subscription.repoName,
+    subscriptionConsumerRepositoryId: environment?.consumerRepoId,
+    subscriptionConsumerRepositoryName: environment?.consumerRepoName,
+    dispatchCertainty: environment?.resolution.status === 'resolved'
+      ? 'environment_declaration_exact' : 'static_name_only',
+    ...(environment?.resolution.status === 'not_applicable' ? {} : {
+      eventEnvironmentResolution: {
+        status: environment?.resolution.status,
+        reason: environment?.resolution.reason,
+        provenance: environment?.resolution.provenance,
+        collisionCount: environment?.collisionCount,
+      },
+    }),
+  };
+}
+
+function handlerAssociationEvidence(
+  subscription: SubscriptionRow,
+  association: HandlerAssociation,
+  call: Partial<HandlerCallRow>,
+  resolutionStatus: string,
+  environmentAmbiguous: boolean,
+  environment?: SubscriptionEnvironmentTarget,
+): Record<string, unknown> {
+  return {
     symbolCallId: call.id,
     roleSiteMatchCount: association.matchCount,
-    callRole: association.matchCount > 0 ? 'event_subscribe_handler' : undefined,
+    callRole: association.matchCount > 0
+      ? 'event_subscribe_handler' : undefined,
     factOrigin: association.factOrigin ?? call.factOrigin,
-    repositoryId: subscription.repoId,
-    repositoryName: subscription.repoName,
     sourceFile: subscription.sourceFile,
     sourceLine: subscription.sourceLine,
     callSiteStartOffset: subscription.startOffset,
@@ -237,14 +300,22 @@ function evidenceFor(
     associationStatus: association.status,
     symbolCallResolutionStatus:
       association.symbolCallResolutionStatus ?? call.status,
-    resolutionStatus: association.status,
+    resolutionStatus,
     resolutionStrategy: call.strategy,
     candidateCount: call.candidateCount,
-    reasonCode: association.reasonCode,
-    ...symbolCallReason,
+    reasonCode: environmentAmbiguous
+      ? environment?.resolution.reason ?? 'event_environment_value_collision'
+      : association.reasonCode,
   };
 }
 
+function eventSkeletonEvidence(
+  value: string | null | undefined,
+): Record<string, unknown> {
+  const skeleton = parseEventSkeletonFact(value);
+  return skeleton ? { eventSkeleton: skeleton } : {};
+}
+
 function boundedSymbolCallReason(
   reason: string | null | undefined,
 ): Record<string, unknown> {
@@ -264,11 +335,14 @@ function insertAssociationEdge(
   subscription: SubscriptionRow,
   association: HandlerAssociation,
   event: LinkedEventTemplate,
+  environment?: SubscriptionEnvironmentTarget,
+  loopValue?: string,
 ): void {
-  const status = event.isDynamic ? 'unresolved' : association.status;
-  const reason = event.isDynamic
-    ? 'event_template_variables_missing'
-    : association.reasonCode ?? association.call?.unresolvedReason ?? null;
+  const ambiguous = environmentTargetAmbiguous(environment);
+  const status = associationEdgeStatus(event, association, ambiguous);
+  const reason = associationEdgeReason(
+    event, association, environment, ambiguous,
+  );
   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
@@ -281,13 +355,134 @@ function insertAssociationEdge(
     association.toKind,
     association.toId,
     association.call?.confidence ?? subscription.confidence,
-    JSON.stringify(evidenceFor(subscription, association, event)),
+    JSON.stringify(evidenceFor(
+      subscription, association, event, environment, loopValue,
+    )),
     event.isDynamic ? 1 : 0,
     reason,
     generation,
   );
 }
 
+function environmentTargetAmbiguous(
+  environment?: SubscriptionEnvironmentTarget,
+): boolean {
+  return environment?.resolution.status === 'ambiguous'
+    || Number(environment?.collisionCount ?? 1) > 1;
+}
+
+function associationEdgeStatus(
+  event: LinkedEventTemplate,
+  association: HandlerAssociation,
+  environmentAmbiguous: boolean,
+): 'resolved' | 'ambiguous' | 'unresolved' {
+  if (event.isDynamic) return 'unresolved';
+  return environmentAmbiguous ? 'ambiguous' : association.status;
+}
+
+function associationEdgeReason(
+  event: LinkedEventTemplate,
+  association: HandlerAssociation,
+  environment: SubscriptionEnvironmentTarget | undefined,
+  environmentAmbiguous: boolean,
+): string | null {
+  if (event.isDynamic)
+    return event.substitution.missing.length > 0
+      ? 'event_template_variables_missing'
+      : event.unresolvedReason ?? 'event_name_unsupported_constant_expression';
+  if (environmentAmbiguous)
+    return environment?.resolution.reason
+      ?? 'event_environment_value_collision';
+  return association.reasonCode ?? association.call?.unresolvedReason ?? null;
+}
+
+function parsedEvidenceRecord(
+  value: string,
+): Record<string, unknown> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function enumeratedLoopValues(
+  evidenceJson: string | null | undefined,
+): string[] | undefined {
+  if (!evidenceJson) return undefined;
+  const evidence = parsedEvidenceRecord(evidenceJson);
+  if (!evidence
+    || evidence.subscriptionLoopRegistrationStatus !== 'enumerated')
+    return undefined;
+  const values = evidence.subscriptionLoopValues;
+  if (!Array.isArray(values)
+    || !values.every((item): item is string => typeof item === 'string'))
+    return undefined;
+  return evidence.subscriptionLoopRegistrationCount === values.length
+    && evidence.omittedSubscriptionLoopValueCount === 0 ? values : undefined;
+}
+
+function linkedSubscriptionEvents(
+  db: Db,
+  workspaceId: number,
+  subscription: SubscriptionRow,
+  variables: Record<string, string>,
+): Array<{
+  event: LinkedEventTemplate;
+  environment: SubscriptionEnvironmentTarget;
+  loopValue?: string;
+}> {
+  const skeleton = parseEventSkeletonFact(subscription.eventSkeletonJson);
+  const environments = subscriptionEnvironmentTargets(
+    db,
+    workspaceId,
+    subscription.packageName ?? undefined,
+    subscription.eventSkeletonJson,
+    subscription.environmentJson,
+    variables,
+  );
+  const loopValues = enumeratedLoopValues(subscription.evidenceJson);
+  const templates = loopValues ?? [subscription.eventName];
+  return environments.flatMap((environment) =>
+    templates.map((template) => ({
+      environment,
+      loopValue: loopValues ? template : undefined,
+      event: linkEventTemplate(
+        template,
+        environment.resolution.variables,
+        loopValues ? undefined : subscription.unresolvedReason ?? undefined,
+        loopValues ? undefined : skeleton,
+      ),
+    })));
+}
+
+function targetStatus(
+  association: HandlerAssociation,
+  event: LinkedEventTemplate,
+  environment: SubscriptionEnvironmentTarget,
+): 'resolved' | 'ambiguous' | 'unresolved' {
+  if (event.isDynamic || association.status === 'unresolved')
+    return 'unresolved';
+  if (association.status === 'ambiguous'
+    || environment.resolution.status === 'ambiguous'
+    || environment.collisionCount > 1) return 'ambiguous';
+  return 'resolved';
+}
+
+function incrementSummary(
+  summary: SubscriptionHandlerLinkSummary,
+  status: 'resolved' | 'ambiguous' | 'unresolved',
+  missing: boolean,
+): void {
+  summary.edgeCount += 1;
+  summary.resolvedCount += status === 'resolved' ? 1 : 0;
+  summary.ambiguousCount += status === 'ambiguous' ? 1 : 0;
+  summary.unresolvedCount += status === 'unresolved' ? 1 : 0;
+  summary.missingAssociationCount += missing ? 1 : 0;
+}
+
 export function linkEventSubscriptionHandlers(
   db: Db,
   workspaceId: number,
@@ -302,22 +497,22 @@ 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, event,
-    );
-    const status = event.isDynamic ? 'unresolved' : association.status;
-    summary.edgeCount += 1;
-    summary.resolvedCount += status === 'resolved' ? 1 : 0;
-    summary.ambiguousCount += status === 'ambiguous' ? 1 : 0;
-    summary.unresolvedCount += status === 'unresolved' ? 1 : 0;
-    summary.missingAssociationCount += association.missing ? 1 : 0;
+    for (const target of linkedSubscriptionEvents(
+      db, workspaceId, subscription, variables,
+    )) {
+      insertAssociationEdge(
+        db, workspaceId, generation, subscription, association,
+        target.event, target.environment, target.loopValue,
+      );
+      incrementSummary(
+        summary,
+        targetStatus(association, target.event, target.environment),
+        association.missing,
+      );
+    }
   }
   return summary;
 }

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

@@ -3,6 +3,14 @@ import {
   substituteVariables,
   type RuntimeSubstitution,
 } from './dynamic-edge-resolver.js';
+import {
+  resolveEventEnvironment,
+} from './event-environment-link.js';
+import {
+  eventTemplateVariables,
+  parseEventSkeletonFact,
+  type EventSkeletonFact,
+} from '../utils/event-skeleton.js';
 
 export interface LinkedEventTemplate {
   targetId: string;
@@ -17,8 +25,11 @@ export function linkEventTemplate(
   template: string,
   variables: Record<string, string>,
   parserReason?: string,
+  skeleton?: EventSkeletonFact,
 ): LinkedEventTemplate {
-  const substitution = substituteVariables(template, variables);
+  const substitution = substituteVariables(
+    template, eventTemplateVariables(skeleton, variables),
+  );
   const missing = substitution.missing.length > 0;
   const unsupportedDynamic = substitution.placeholders.length === 0
     && parserReason !== undefined;
@@ -47,18 +58,41 @@ export function insertEventCallEdge(
   evidence: Record<string, unknown>,
 ): { status: string; callType: string } {
   const callType = String(call.call_type);
+  const skeleton = parseEventSkeletonFact(call.event_skeleton_json);
+  const environment = resolveEventEnvironment(
+    call.event_skeleton_json,
+    call.environmentDeclarationsJson,
+    variables,
+  );
   const event = linkEventTemplate(
-    String(call.event_name_expr ?? ''), variables,
+    String(call.event_name_expr ?? ''), environment.variables,
     typeof call.unresolved_reason === 'string'
       ? call.unresolved_reason : undefined,
+    skeleton,
   );
   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;
+  const eventEvidence = {
+    ...evidence,
+    dispatchScope: 'workspace_event_name_only',
+    dispatchCertainty: environment.status === 'resolved'
+      ? 'environment_declaration_exact'
+      : event.isDynamic ? 'runtime_variables_required' : 'static_name_only',
+    ...(skeleton ? { eventSkeleton: skeleton } : {}),
+    ...(event.substitution.placeholders.length > 0
+      ? { eventTemplateResolution: event.substitution } : {}),
+    ...(environment.status === 'not_applicable' ? {} : {
+      eventEnvironmentResolution: {
+        status: environment.status,
+        reason: environment.reason,
+        provenance: environment.provenance,
+      },
+    }),
+  };
+  const unresolvedReason = environment.reason
+    ?? event.unresolvedReason;
   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
@@ -66,7 +100,7 @@ export function insertEventCallEdge(
     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,
+    unresolvedReason ?? null, generation,
   );
   return { status: event.status, callType };
 }