@saptools/service-flow 0.1.72 → 0.1.73

package/src/db/package-target-invalidation.ts

@@ -161,9 +161,10 @@ function resetPackageEventCalls(
     const source = call.evidence.eventNameConstantSourceExpression;
     if (typeof source !== 'string' || source.length === 0)
       throw new Error('invalid_current_package_event_constant_evidence');
-    const reason = call.evidence.receiverClassification === 'unproven'
-      ? call.unresolvedReason : 'event_name_constant_resolution_pending';
-    update.run(source, reason, pendingEventEvidence(call.evidence), call.id);
+    update.run(
+      source, 'event_name_constant_resolution_pending',
+      pendingEventEvidence(call.evidence), call.id,
+    );
     batch.affectedCallerRepoIds.add(call.repoId);
     matched = true;
   }

package/src/db/schema.ts

@@ -1,6 +1,6 @@
 export const schemaTablesSql = `
 CREATE TABLE IF NOT EXISTS workspaces (id INTEGER PRIMARY KEY, root_path TEXT UNIQUE NOT NULL, db_path TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
-CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', package_public_surface_json TEXT, environment_declarations_json TEXT DEFAULT '{"schema":"service-flow/environment-declarations@1","status":"not_applicable","reason":null,"recordCap":32,"total":0,"shown":0,"omitted":0,"declarations":[]}', kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, fingerprint TEXT, fact_generation INTEGER NOT NULL DEFAULT 0, graph_generation INTEGER NOT NULL DEFAULT 0, graph_stale_reason TEXT, graph_stale_at TEXT, fact_analyzer_version TEXT, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', package_public_surface_json TEXT, environment_declarations_json TEXT DEFAULT '{"schema":"service-flow/environment-declarations@1","allowedKeys":["SHARD_CODE"],"status":"not_applicable","reason":null,"recordCap":32,"total":0,"shown":0,"omitted":0,"declarations":[]}', kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, fingerprint TEXT, fact_generation INTEGER NOT NULL DEFAULT 0, graph_generation INTEGER NOT NULL DEFAULT 0, graph_stale_reason TEXT, graph_stale_at TEXT, fact_analyzer_version TEXT, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS files (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, relative_path TEXT NOT NULL, extension TEXT NOT NULL, sha256 TEXT NOT NULL, size_bytes INTEGER NOT NULL, last_indexed_at TEXT NOT NULL, UNIQUE(repo_id, relative_path), FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS cds_requires (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, alias TEXT NOT NULL, kind TEXT, model TEXT, destination TEXT, service_path TEXT, request_timeout INTEGER, raw_json TEXT NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS cds_services (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, namespace TEXT, service_name TEXT NOT NULL, qualified_name TEXT NOT NULL, service_path TEXT NOT NULL, is_extend INTEGER NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, extension_local_ref TEXT, extension_imported_symbol TEXT, extension_local_alias TEXT, extension_module_specifier TEXT, extension_import_kind TEXT, extension_base_service_id INTEGER, extension_base_status TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(extension_base_service_id) REFERENCES cds_services(id) ON DELETE SET NULL);

package/src/indexer/repository-indexer.ts

@@ -56,6 +56,7 @@ import {
 import {
   loadRepositorySourceContext,
   type RepositorySourceContext,
+  type SourceFileSnapshot,
   type SourceContextInstrumentation,
 } from '../parsers/ts-project.js';
 import {
@@ -128,6 +129,7 @@ export async function prepareRepositoryIndex(
   repo: RepoRow,
   force: boolean,
   instrumentation?: SourceContextInstrumentation,
+  eventEnvironmentKeys?: readonly string[],
 ): Promise<PreparedRepositoryIndex> {
   const sourceFiles = await findSourceFiles(repo.absolute_path);
   const packageSnapshot = await loadPackageJsonSnapshot(repo.absolute_path, {
@@ -138,11 +140,17 @@ export async function prepareRepositoryIndex(
   const sources = await loadRepositorySourceContext(
     repo.absolute_path, sourceFiles, instrumentation,
   );
+  const environmentDeclarations = collectEnvironmentDeclarations(
+    sources, eventEnvironmentKeys,
+  );
   const fingerprint = repositoryFingerprint(
-    sources, packageFacts, packageSnapshot.rawText,
+    sources, packageFacts, packageSnapshot.rawText, environmentDeclarations,
   );
   if (!force && repo.fingerprint === fingerprint) return { repo, fileCount: 0, diagnosticCount: 0, skipped: true };
-  const parsedFacts = await parseAllSourceFacts(repo.absolute_path, sources);
+  const parsedFacts = await parseAllSourceFacts(
+    repo.absolute_path, sources, environmentDeclarations,
+    eventEnvironmentKeys,
+  );
   const packageSurface = analyzeRepositoryPackageSurface(
     packageFacts, packageSnapshot.manifest, sources,
   );
@@ -157,7 +165,7 @@ export async function prepareRepositoryIndex(
     kind: await classifyRepository(repo.absolute_path, packageFacts),
     parsed,
     packagePublicSurface: packageSurface.surface,
-    environmentDeclarations: collectEnvironmentDeclarations(sources),
+    environmentDeclarations,
     fileCount: sourceFiles.length,
     diagnosticCount: parsed.handlers.filter((handler) =>
       handler.hasHandlerDecorator
@@ -269,11 +277,18 @@ export function recordIndexFailure(db: Db, repoId: number, error: unknown): void
 async function parseAllSourceFacts(
   root: string,
   sources: RepositorySourceContext,
+  environmentDeclarations: EnvironmentDeclarationsFact,
+  eventEnvironmentKeys?: readonly string[],
 ): Promise<ParsedFacts> {
   const facts: ParsedFacts = { services: [], handlers: [], registrations: [], bindings: [], calls: [], symbols: [], symbolCalls: [], generatedConstants: [], fileRecords: [] };
   for (const snapshot of sources.entries()) {
     const file = snapshot.filePath;
-    facts.fileRecords.push({ relativePath: normalizePath(file), extension: path.extname(file), sha256: sha256Text(snapshot.text), sizeBytes: snapshot.sizeBytes });
+    facts.fileRecords.push({
+      relativePath: normalizePath(file),
+      extension: path.extname(file),
+      sha256: sourceFactHash(snapshot, environmentDeclarations),
+      sizeBytes: snapshot.sizeBytes,
+    });
     if (file.endsWith('.cds')) facts.services.push(...(await parseCdsFile(root, file, sources)));
     if (/\.[jt]s$/.test(file)) {
       const source = snapshot.sourceFile();
@@ -283,7 +298,9 @@ async function parseAllSourceFacts(
           sources, source, file,
         ),
         eventEnvironmentReferenceResolver:
-          createEventEnvironmentReferenceResolver(sources, source, file),
+          createEventEnvironmentReferenceResolver(
+            sources, source, file, eventEnvironmentKeys,
+          ),
       });
       facts.handlers.push(...(await parseDecorators(root, file, sources)));
       facts.registrations.push(...(await parseHandlerRegistrations(root, file, sources)));
@@ -334,6 +351,7 @@ function repositoryFingerprint(
   sources: RepositorySourceContext,
   facts: PackageFacts,
   packageJsonText: string,
+  environmentDeclarations: EnvironmentDeclarationsFact,
 ): string {
   const normalizedFacts = {
     analyzerVersion: ANALYZER_VERSION,
@@ -343,10 +361,36 @@ function repositoryFingerprint(
     cdsRequires: [...facts.cdsRequires].sort((a, b) => a.alias.localeCompare(b.alias)),
     scripts: Object.fromEntries(Object.entries(facts.scripts).sort()),
     includeTests: false,
+    eventEnvironmentKeys: environmentDeclarations.allowedKeys,
     packageJsonHash: sha256Text(packageJsonText),
   };
   const entries: string[] = [`facts:${JSON.stringify(normalizedFacts)}`];
   for (const snapshot of sources.entries())
-    entries.push(`${snapshot.filePath}:${sha256Text(snapshot.text)}`);
+    entries.push(
+      `${snapshot.filePath}:${
+        sourceFactHash(snapshot, environmentDeclarations)}`,
+    );
   return sha256Text(entries.join('\n'));
 }
+
+function sourceFactHash(
+  snapshot: SourceFileSnapshot,
+  environmentDeclarations: EnvironmentDeclarationsFact,
+): string {
+  if (!isEnvironmentFactInput(snapshot.filePath))
+    return sha256Text(snapshot.text);
+  const declarations = environmentDeclarations.declarations.filter(
+    (item) => item.sourceFile === snapshot.filePath,
+  );
+  return sha256Text(JSON.stringify({
+    allowedKeys: environmentDeclarations.allowedKeys,
+    declarations,
+  }));
+}
+
+function isEnvironmentFactInput(filePath: string): boolean {
+  const name = filePath.split('/').at(-1);
+  return ['nodemon.json', '.env', 'mta.yaml', 'manifest.yml'].includes(
+    name ?? '',
+  );
+}

package/src/indexer/workspace-indexer.ts

@@ -104,7 +104,12 @@ export interface IndexWorkspaceSummary {
 export async function indexWorkspace(
   db: Db,
   workspaceId: number,
-  options: { repo?: string; force: boolean; injectDerivedMaterializationFailure?: boolean },
+  options: {
+    repo?: string;
+    force: boolean;
+    eventEnvironmentKeys?: readonly string[];
+    injectDerivedMaterializationFailure?: boolean;
+  },
 ): Promise<IndexWorkspaceSummary> {
   const repos = selectedRepositories(db, workspaceId, options.repo);
   const runId = claimIndexRun(db, workspaceId, repos.length);
@@ -112,7 +117,9 @@ export async function indexWorkspace(
     fileCount: 0, diagnosticCount: 0, skippedCount: 0, rows: [],
   };
   try {
-    await prepareRepositories(repos, options.force, state);
+    await prepareRepositories(
+      repos, options.force, state, options.eventEnvironmentKeys,
+    );
     return publishPreparedWorkspaceRows(
       db, workspaceId, runId, state.rows, options,
     );
@@ -168,10 +175,13 @@ async function prepareRepositories(
   repos: readonly IndexRepository[],
   force: boolean,
   state: PreparationState,
+  eventEnvironmentKeys?: readonly string[],
 ): Promise<void> {
   for (const repo of repos) {
     state.activeRepoId = repo.id;
-    const result = await prepareRepositoryIndex(repo, force);
+    const result = await prepareRepositoryIndex(
+      repo, force, undefined, eventEnvironmentKeys,
+    );
     state.rows.push(result);
     state.fileCount += result.fileCount;
     state.diagnosticCount += result.diagnosticCount;

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

@@ -27,6 +27,7 @@ export interface LinkWorkspaceResult {
   subscriptionHandlerUnresolvedCount: number;
   subscriptionHandlerMissingAssociationCount: number;
   eventShapeCandidateCount: number;
+  eventShapeCandidateOmittedCount: number;
 }
 export function linkWorkspace(db: Db, workspaceId: number, vars: Record<string, string> = {}): LinkWorkspaceResult {
   return db.transaction(() => {
@@ -46,7 +47,7 @@ export function linkWorkspace(db: Db, workspaceId: number, vars: Record<string,
     const impl = linkCanonicalImplementations(db, workspaceId, generation);
     const callSummary = linkCalls(db, workspaceId, vars, 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 + subscriptions.edgeCount + eventShapes.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount, implementationUnresolvedCount: impl.unresolvedCount, subscriptionHandlerResolvedCount: subscriptions.resolvedCount, subscriptionHandlerAmbiguousCount: subscriptions.ambiguousCount, subscriptionHandlerUnresolvedCount: subscriptions.unresolvedCount, subscriptionHandlerMissingAssociationCount: subscriptions.missingAssociationCount, eventShapeCandidateCount: eventShapes.edgeCount };
+    return { ...callSummary, edgeCount: deps.edgeCount + callSummary.edgeCount + impl.edgeCount + subscriptions.edgeCount + eventShapes.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount, implementationUnresolvedCount: impl.unresolvedCount, subscriptionHandlerResolvedCount: subscriptions.resolvedCount, subscriptionHandlerAmbiguousCount: subscriptions.ambiguousCount, subscriptionHandlerUnresolvedCount: subscriptions.unresolvedCount, subscriptionHandlerMissingAssociationCount: subscriptions.missingAssociationCount, eventShapeCandidateCount: eventShapes.edgeCount, eventShapeCandidateOmittedCount: eventShapes.omittedCount };
   });
 }
 function nextGraphGeneration(db: Db, workspaceId: number): number {
@@ -63,7 +64,8 @@ type CallLinkSummary = Omit<LinkWorkspaceResult,
   | 'subscriptionHandlerAmbiguousCount'
   | 'subscriptionHandlerUnresolvedCount'
   | 'subscriptionHandlerMissingAssociationCount'
-  | 'eventShapeCandidateCount'>;
+  | 'eventShapeCandidateCount'
+  | 'eventShapeCandidateOmittedCount'>;
 
 function linkCalls(db: Db, workspaceId: number, vars: Record<string, string>, generation: number): CallLinkSummary {
   let edgeCount = 0;

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

@@ -1,16 +1,21 @@
 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> {
@@ -20,6 +25,7 @@ interface SubscriberAssociation extends Record<string, unknown> {
   targetId: string;
   status: string;
   evidenceJson: string;
+  targetLabel?: string | null;
 }
 
 function eventRows(
@@ -29,7 +35,7 @@ function eventRows(
 ): 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.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
@@ -46,15 +52,19 @@ function associations(
   workspaceId: number,
   generation: number,
 ): SubscriberAssociation[] {
-  return db.prepare(`SELECT id graphEdgeId,
-    CAST(json_extract(evidence_json,'$.subscribeCallId') AS INTEGER)
+  return db.prepare(`SELECT edge.id graphEdgeId,
+    CAST(json_extract(edge.evidence_json,'$.subscribeCallId') AS INTEGER)
       subscribeCallId,
-    to_kind targetKind,to_id targetId,status,evidence_json evidenceJson
-    FROM graph_edges
-    WHERE workspace_id=? AND generation=?
-      AND edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
-      AND to_kind='symbol'
-    ORDER BY subscribeCallId,id`).all(
+    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[];
 }
@@ -85,8 +95,11 @@ 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,
@@ -100,7 +113,12 @@ function candidateEvidence(
     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),
   };
 }
 
@@ -111,6 +129,8 @@ function insertCandidate(
   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,
@@ -125,7 +145,7 @@ function insertCandidate(
     association.targetId,
     0.3,
     JSON.stringify(candidateEvidence(
-      emit, subscribe, association,
+      emit, subscribe, association, total, shown,
     )),
     1,
     'event_skeleton_equivalent_non_authoritative',
@@ -133,6 +153,24 @@ function insertCandidate(
   );
 }
 
+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,
@@ -147,15 +185,20 @@ export function linkEventShapeCandidates(
       association,
     ]);
   let edgeCount = 0;
-  for (const emit of emits)
-    for (const subscription of subscriptions) {
-      if (!candidateEligible(emit, subscription)) continue;
-      for (const association of bySubscription.get(subscription.id) ?? []) {
-        insertCandidate(
-          db, workspaceId, generation, emit, subscription, association,
-        );
-        edgeCount += 1;
-      }
+  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;
     }
-  return { edgeCount };
+    omittedCount += Math.max(0, candidates.length - shown.length);
+  }
+  return { edgeCount, omittedCount };
 }

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

@@ -33,6 +33,7 @@ interface SubscriptionRow {
   packageName?: string | null;
   environmentJson?: string | null;
   eventSkeletonJson?: string | null;
+  evidenceJson?: string | null;
 }
 
 interface HandlerCallRow {
@@ -73,6 +74,7 @@ function subscriptionRows(db: Db, workspaceId: number): SubscriptionRow[] {
     c.call_site_start_offset startOffset,c.call_site_end_offset endOffset,
     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
@@ -220,6 +222,7 @@ function evidenceFor(
   association: HandlerAssociation,
   event: LinkedEventTemplate,
   environment?: SubscriptionEnvironmentTarget,
+  loopValue?: string,
 ): Record<string, unknown> {
   const call: Partial<HandlerCallRow> = association.call ?? {};
   const symbolCallReason = boundedSymbolCallReason(call.unresolvedReason);
@@ -228,8 +231,25 @@ function evidenceFor(
   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,
@@ -238,10 +258,6 @@ function evidenceFor(
     associationBasis: 'exact_subscription_call_span',
     dispatchScope: 'workspace_event_name_only',
     subscribeCallId: subscription.id,
-    symbolCallId: call.id,
-    roleSiteMatchCount: association.matchCount,
-    callRole: association.matchCount > 0 ? 'event_subscribe_handler' : undefined,
-    factOrigin: association.factOrigin ?? call.factOrigin,
     repositoryId: subscription.repoId,
     repositoryName: subscription.repoName,
     subscriptionConsumerRepositoryId: environment?.consumerRepoId,
@@ -256,6 +272,23 @@ function evidenceFor(
         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,
+    factOrigin: association.factOrigin ?? call.factOrigin,
     sourceFile: subscription.sourceFile,
     sourceLine: subscription.sourceLine,
     callSiteStartOffset: subscription.startOffset,
@@ -273,7 +306,6 @@ function evidenceFor(
     reasonCode: environmentAmbiguous
       ? environment?.resolution.reason ?? 'event_environment_value_collision'
       : association.reasonCode,
-    ...symbolCallReason,
   };
 }
 
@@ -304,20 +336,13 @@ function insertAssociationEdge(
   association: HandlerAssociation,
   event: LinkedEventTemplate,
   environment?: SubscriptionEnvironmentTarget,
+  loopValue?: string,
 ): void {
-  const environmentAmbiguous = environment?.resolution.status === 'ambiguous'
-    || Number(environment?.collisionCount ?? 1) > 1;
-  const status = event.isDynamic
-    ? 'unresolved'
-    : environmentAmbiguous ? 'ambiguous' : association.status;
-  const reason = event.isDynamic
-    ? event.substitution.missing.length > 0
-      ? 'event_template_variables_missing'
-      : event.unresolvedReason ?? 'event_name_unsupported_constant_expression'
-    : environmentAmbiguous
-      ? environment?.resolution.reason
-        ?? 'event_environment_value_collision'
-    : 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
@@ -331,7 +356,7 @@ function insertAssociationEdge(
     association.toId,
     association.call?.confidence ?? subscription.confidence,
     JSON.stringify(evidenceFor(
-      subscription, association, event, environment,
+      subscription, association, event, environment, loopValue,
     )),
     event.isDynamic ? 1 : 0,
     reason,
@@ -339,6 +364,66 @@ function insertAssociationEdge(
   );
 }
 
+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,
@@ -347,24 +432,30 @@ function linkedSubscriptionEvents(
 ): Array<{
   event: LinkedEventTemplate;
   environment: SubscriptionEnvironmentTarget;
+  loopValue?: string;
 }> {
   const skeleton = parseEventSkeletonFact(subscription.eventSkeletonJson);
-  return subscriptionEnvironmentTargets(
+  const environments = subscriptionEnvironmentTargets(
     db,
     workspaceId,
     subscription.packageName ?? undefined,
     subscription.eventSkeletonJson,
     subscription.environmentJson,
     variables,
-  ).map((environment) => ({
-    environment,
-    event: linkEventTemplate(
-      subscription.eventName,
-      environment.resolution.variables,
-      subscription.unresolvedReason ?? undefined,
-      skeleton,
-    ),
-  }));
+  );
+  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(
@@ -414,7 +505,7 @@ export function linkEventSubscriptionHandlers(
     )) {
       insertAssociationEdge(
         db, workspaceId, generation, subscription, association,
-        target.event, target.environment,
+        target.event, target.environment, target.loopValue,
       );
       incrementSummary(
         summary,