@saptools/service-flow 0.1.70 → 0.1.72

package/dist/index.d.ts

@@ -1,7 +1,45 @@
 import ts from 'typescript';
 
+interface SourceFileSnapshot {
+    repoPath: string;
+    filePath: string;
+    text: string;
+    sizeBytes: number;
+    sourceFile: () => ts.SourceFile;
+}
+interface RepositorySourceContext {
+    get: (filePath: string) => SourceFileSnapshot | undefined;
+    entries: () => SourceFileSnapshot[];
+}
+
+type EventEnvironmentTransform = 'toUpperCase' | 'toLowerCase';
+interface EventEnvironmentReference {
+    status: 'resolved' | 'refused';
+    sourceKey: string;
+    environmentKey?: string;
+    transforms: EventEnvironmentTransform[];
+    sourceFile?: string;
+    startOffset?: number;
+    endOffset?: number;
+    reason?: string;
+}
+
+declare const EVENT_SKELETON_SCHEMA = "service-flow/event-skeleton@1";
+interface EventSkeletonFact {
+    schema: typeof EVENT_SKELETON_SCHEMA;
+    status: 'complete' | 'malformed' | 'too_large';
+    signature: string | null;
+    literalSpans: string[];
+    holeCount: number;
+    sourceKeys: string[];
+    canonicalKeys: string[];
+    candidateEligible: boolean;
+    environmentBindings: EventEnvironmentReference[];
+    reason?: string;
+}
+
 type CallType = 'remote_action' | 'remote_query' | 'remote_entity_read' | 'remote_entity_mutation' | 'remote_entity_delete' | 'remote_entity_media' | 'remote_entity_candidate' | 'local_db_query' | 'external_http' | 'async_emit' | 'async_subscribe' | 'local_service_call' | 'unknown';
-type EdgeType = 'REPO_HAS_SERVICE' | 'SERVICE_HAS_OPERATION' | 'OPERATION_IMPLEMENTED_BY_HANDLER' | 'HANDLER_REGISTERED_BY_SERVER' | 'HANDLER_CALLS_LOCAL_FUNCTION' | 'HANDLER_USES_SERVICE_ALIAS' | 'HANDLER_CALLS_REMOTE_OPERATION' | 'REMOTE_CALL_RESOLVES_TO_OPERATION' | 'LOCAL_CALL_RESOLVES_TO_OPERATION' | 'HANDLER_RUNS_DB_QUERY' | 'HANDLER_RUNS_REMOTE_QUERY' | 'HANDLER_ACCESSES_REMOTE_ENTITY' | 'HANDLER_CALLS_EXTERNAL_HTTP' | 'HANDLER_CALLS_TRANSPORT_METHOD' | 'HANDLER_EMITS_EVENT' | 'EVENT_CONSUMED_BY_HANDLER' | 'EVENT_SUBSCRIPTION_HANDLED_BY' | 'REPO_IMPORTS_HELPER_PACKAGE' | 'HELPER_PACKAGE_PROVIDES_HANDLER' | 'DYNAMIC_EDGE_CANDIDATE' | 'UNRESOLVED_EDGE';
+type EdgeType = 'REPO_HAS_SERVICE' | 'SERVICE_HAS_OPERATION' | 'OPERATION_IMPLEMENTED_BY_HANDLER' | 'HANDLER_REGISTERED_BY_SERVER' | 'HANDLER_CALLS_LOCAL_FUNCTION' | 'HANDLER_USES_SERVICE_ALIAS' | 'HANDLER_CALLS_REMOTE_OPERATION' | 'REMOTE_CALL_RESOLVES_TO_OPERATION' | 'LOCAL_CALL_RESOLVES_TO_OPERATION' | 'HANDLER_RUNS_DB_QUERY' | 'HANDLER_RUNS_REMOTE_QUERY' | 'HANDLER_ACCESSES_REMOTE_ENTITY' | 'HANDLER_CALLS_EXTERNAL_HTTP' | 'HANDLER_CALLS_TRANSPORT_METHOD' | 'HANDLER_EMITS_EVENT' | 'EVENT_CONSUMED_BY_HANDLER' | 'EVENT_SUBSCRIPTION_HANDLED_BY' | 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER' | 'REPO_IMPORTS_HELPER_PACKAGE' | 'HELPER_PACKAGE_PROVIDES_HANDLER' | 'DYNAMIC_EDGE_CANDIDATE' | 'UNRESOLVED_EDGE';
 interface DiscoveredRepository {
     name: string;
     absolutePath: string;
@@ -149,6 +187,7 @@ interface OutboundCallFact {
     operationPathExpr?: string;
     queryEntity?: string;
     eventNameExpr?: string;
+    eventSkeleton?: EventSkeletonFact;
     payloadSummary?: string;
     sourceFile: string;
     sourceLine: number;
@@ -194,9 +233,20 @@ interface SymbolCallFact {
 }
 interface GeneratedConstantFact {
     name: string;
-    value: string;
+    value?: string;
     sourceFile: string;
     sourceLine: number;
+    containerName?: string;
+    memberName?: string;
+    constantKind: 'const_identifier' | 'enum_member' | 'const_object_property';
+    exported: boolean;
+    stable: boolean;
+    resolutionStatus: 'resolved' | 'refused';
+    unresolvedReason?: 'event_name_constant_member_not_string' | 'event_name_constant_container_mutable';
+    declarationStartOffset: number;
+    declarationEndOffset: number;
+    valueStartOffset: number;
+    valueEndOffset: number;
 }
 interface TraceStart {
     repo?: string;
@@ -250,18 +300,6 @@ interface ParsePackageJsonOptions {
 }
 declare function parsePackageJson(repoPath: string, options?: ParsePackageJsonOptions): Promise<PackageFacts>;
 
-interface SourceFileSnapshot {
-    repoPath: string;
-    filePath: string;
-    text: string;
-    sizeBytes: number;
-    sourceFile: () => ts.SourceFile;
-}
-interface RepositorySourceContext {
-    get: (filePath: string) => SourceFileSnapshot | undefined;
-    entries: () => SourceFileSnapshot[];
-}
-
 declare function parseCdsFile(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<CdsServiceFact[]>;
 
 declare function parseDecorators(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<HandlerClassFact[]>;
@@ -314,6 +352,7 @@ interface LinkWorkspaceResult {
     subscriptionHandlerAmbiguousCount: number;
     subscriptionHandlerUnresolvedCount: number;
     subscriptionHandlerMissingAssociationCount: number;
+    eventShapeCandidateCount: number;
 }
 declare function linkWorkspace(db: Db, workspaceId: number, vars?: Record<string, string>): LinkWorkspaceResult;
 

package/dist/index.js

@@ -5,9 +5,9 @@ import {
   discoverRepositories,
   extractPlaceholders,
   linkWorkspace,
-  normalizePath,
   parseCdsFile,
   parseDecorators,
+  parseGeneratedConstants,
   parseHandlerRegistrations,
   parseImplementationHint,
   parseOutboundCalls,
@@ -15,31 +15,10 @@ import {
   parseServiceBindings,
   redactText,
   redactValue,
-  stripQuotes,
   substituteVariables,
   trace,
   traceAndCompact
-} from "./chunk-GSLFY6J2.js";
-
-// src/parsers/generated-constants-parser.ts
-import fs from "fs/promises";
-import path from "path";
-function lineOf(text, idx) {
-  return text.slice(0, idx).split("\n").length;
-}
-async function parseGeneratedConstants(repoPath, filePath) {
-  const text = await fs.readFile(path.join(repoPath, filePath), "utf8");
-  return [
-    ...text.matchAll(
-      /(?:export\s+)?(?:const|static\s+readonly)\s+(\w+)\s*=\s*(['"])([^'"]+)\2/g
-    )
-  ].map((m) => ({
-    name: m[1] ?? "constant",
-    value: stripQuotes(m[3] ?? ""),
-    sourceFile: normalizePath(filePath),
-    sourceLine: lineOf(text, m.index ?? 0)
-  }));
-}
+} from "./chunk-Z6D433R5.js";
 export {
   applyVariables,
   compactTrace,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/parsers/generated-constants-parser.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport type { GeneratedConstantFact } from '../types.js';\nimport { normalizePath, stripQuotes } from '../utils/path-utils.js';\nfunction lineOf(text: string, idx: number): number {\n  return text.slice(0, idx).split('\\n').length;\n}\nexport async function parseGeneratedConstants(\n  repoPath: string,\n  filePath: string\n): Promise<GeneratedConstantFact[]> {\n  const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');\n  return [\n    ...text.matchAll(\n      /(?:export\\s+)?(?:const|static\\s+readonly)\\s+(\\w+)\\s*=\\s*(['\"])([^'\"]+)\\2/g\n    )\n  ].map((m) => ({\n    name: m[1] ?? 'constant',\n    value: stripQuotes(m[3] ?? ''),\n    sourceFile: normalizePath(filePath),\n    sourceLine: lineOf(text, m.index ?? 0)\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AAGjB,SAAS,OAAO,MAAc,KAAqB;AACjD,SAAO,KAAK,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE;AACxC;AACA,eAAsB,wBACpB,UACA,UACkC;AAClC,QAAM,OAAO,MAAM,GAAG,SAAS,KAAK,KAAK,UAAU,QAAQ,GAAG,MAAM;AACpE,SAAO;AAAA,IACL,GAAG,KAAK;AAAA,MACN;AAAA,IACF;AAAA,EACF,EAAE,IAAI,CAAC,OAAO;AAAA,IACZ,MAAM,EAAE,CAAC,KAAK;AAAA,IACd,OAAO,YAAY,EAAE,CAAC,KAAK,EAAE;AAAA,IAC7B,YAAY,cAAc,QAAQ;AAAA,IAClC,YAAY,OAAO,MAAM,EAAE,SAAS,CAAC;AAAA,EACvC,EAAE;AACJ;","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saptools/service-flow",
-  "version": "0.1.70",
+  "version": "0.1.72",
   "description": "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   "type": "module",
   "publishConfig": {

package/src/cli/doctor-event-quality.ts

@@ -0,0 +1,371 @@
+import type { Db } from '../db/connection.js';
+
+type Diagnostic = Record<string, unknown>;
+
+const eventNameReason = `COALESCE(
+  json_extract(c.evidence_json,'$.eventNameUnresolvedReason'),
+  CASE WHEN c.unresolved_reason GLOB 'dynamic_event_name_*'
+    OR c.unresolved_reason GLOB 'event_name_*'
+    THEN c.unresolved_reason END
+)`;
+
+function workspacePredicate(alias: string): string {
+  return `(? IS NULL OR ${alias}.workspace_id=?)`;
+}
+
+function count(value: unknown): number {
+  return Number(value ?? 0);
+}
+
+function unresolvedEventNameExamples(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return db.prepare(`SELECT r.name repositoryName,
+    c.source_file sourceFile,c.source_line sourceLine,
+    c.event_name_expr eventName,${eventNameReason} reason
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type='async_emit' AND ${workspacePredicate('r')}
+      AND ${eventNameReason} IS NOT NULL
+    ORDER BY r.name COLLATE BINARY,c.source_file COLLATE BINARY,
+      c.source_line,c.id LIMIT 5`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+}
+
+function eventNameResolutionQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const aggregate = db.prepare(`SELECT COUNT(*) total,
+    SUM(CASE WHEN reason IS NOT NULL THEN 1 ELSE 0 END) unresolved
+    FROM (SELECT ${eventNameReason} reason
+      FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+      WHERE c.call_type='async_emit' AND ${workspacePredicate('r')})`).get(
+    workspaceId, workspaceId,
+  );
+  const reasons = db.prepare(`SELECT ${eventNameReason} reason,COUNT(*) count
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type='async_emit' AND ${workspacePredicate('r')}
+      AND ${eventNameReason} IS NOT NULL
+    GROUP BY reason ORDER BY count DESC,reason COLLATE BINARY LIMIT 16`).all(
+    workspaceId, workspaceId,
+  );
+  const unresolved = count(aggregate?.unresolved);
+  return {
+    severity: unresolved > 0 ? 'warning' : 'info',
+    code: 'strict_event_name_resolution_quality',
+    message: 'Event publication name-resolution aggregate',
+    publicationTotal: count(aggregate?.total),
+    unresolvedPublicationCount: unresolved,
+    reasonBuckets: reasons,
+    examples: unresolvedEventNameExamples(db, workspaceId),
+    exampleCount: unresolved,
+  };
+}
+
+function dynamicEventExamples(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return db.prepare(`SELECT r.name repositoryName,c.call_type callType,
+    c.source_file sourceFile,c.source_line sourceLine,
+    e.to_kind targetKind,e.to_id targetId,e.unresolved_reason reason
+    FROM graph_edges e JOIN outbound_calls c
+      ON e.from_kind='call' AND c.id=CAST(e.from_id AS INTEGER)
+    JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type IN ('async_emit','async_subscribe')
+      AND ${workspacePredicate('r')}
+      AND (e.to_kind='event_candidate'
+        OR e.edge_type='DYNAMIC_EDGE_CANDIDATE')
+    ORDER BY r.name COLLATE BINARY,c.source_file COLLATE BINARY,
+      c.source_line,c.id LIMIT 5`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+}
+
+function dynamicEventQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const row = db.prepare(`SELECT
+    COUNT(DISTINCT CASE WHEN e.to_kind='event_candidate'
+      THEN e.workspace_id || ':' || e.to_id END) eventCandidateNodeCount,
+    COUNT(*) dynamicEventEdgeCount,
+    SUM(CASE WHEN json_array_length(e.evidence_json,
+      '$.eventTemplateResolution.placeholders')>0 THEN 1 ELSE 0 END)
+      variableRecoverableCount
+    FROM graph_edges e JOIN outbound_calls c
+      ON e.from_kind='call' AND c.id=CAST(e.from_id AS INTEGER)
+    JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type IN ('async_emit','async_subscribe')
+      AND ${workspacePredicate('r')}
+      AND (e.to_kind='event_candidate'
+        OR e.edge_type='DYNAMIC_EDGE_CANDIDATE')`).get(
+    workspaceId, workspaceId,
+  );
+  const total = count(row?.dynamicEventEdgeCount);
+  const recoverable = count(row?.variableRecoverableCount);
+  return {
+    severity: total > 0 ? 'warning' : 'info',
+    code: 'strict_event_dynamic_candidate_quality',
+    message: 'Dynamic event candidate aggregate',
+    eventCandidateNodeCount: count(row?.eventCandidateNodeCount),
+    dynamicEventEdgeCount: total,
+    eventCandidateCount: total,
+    variableRecoverableCount: recoverable,
+    nonVariableRecoverableCount: Math.max(0, total - recoverable),
+    examples: dynamicEventExamples(db, workspaceId),
+    exampleCount: total,
+  };
+}
+
+function unmatchedPublicationRows(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return db.prepare(`SELECT r.name repositoryName,c.source_file sourceFile,
+    c.source_line sourceLine,e.to_id eventName
+    FROM graph_edges e JOIN outbound_calls c
+      ON e.from_kind='call' AND c.id=CAST(e.from_id AS INTEGER)
+    JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type='async_emit' AND e.edge_type='HANDLER_EMITS_EVENT'
+      AND e.to_kind='event' AND ${workspacePredicate('r')}
+      AND NOT EXISTS (SELECT 1 FROM graph_edges subscription
+        WHERE subscription.workspace_id=e.workspace_id
+          AND subscription.generation=e.generation
+          AND subscription.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+          AND subscription.from_kind='event'
+          AND subscription.from_id=e.to_id)
+    ORDER BY r.name COLLATE BINARY,c.source_file COLLATE BINARY,
+      c.source_line,c.id LIMIT 5`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+}
+
+function unmatchedPublicationQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const row = db.prepare(`SELECT COUNT(*) count
+    FROM graph_edges e JOIN outbound_calls c
+      ON e.from_kind='call' AND c.id=CAST(e.from_id AS INTEGER)
+    JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type='async_emit' AND e.edge_type='HANDLER_EMITS_EVENT'
+      AND e.to_kind='event' AND ${workspacePredicate('r')}
+      AND NOT EXISTS (SELECT 1 FROM graph_edges subscription
+        WHERE subscription.workspace_id=e.workspace_id
+          AND subscription.generation=e.generation
+          AND subscription.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+          AND subscription.from_kind='event'
+          AND subscription.from_id=e.to_id)`).get(workspaceId, workspaceId);
+  const total = count(row?.count);
+  return {
+    severity: total > 0 ? 'warning' : 'info',
+    code: 'strict_event_publication_without_subscription_quality',
+    message: 'Resolved event publications without a matching subscription',
+    unmatchedPublicationCount: total,
+    examples: unmatchedPublicationRows(db, workspaceId),
+    exampleCount: total,
+  };
+}
+
+function unmatchedSubscriptionRows(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return db.prepare(`SELECT COALESCE(json_extract(e.evidence_json,
+      '$.subscriptionConsumerRepositoryName'),
+      json_extract(e.evidence_json,'$.repositoryName')) repositoryName,
+    json_extract(e.evidence_json,'$.sourceFile') sourceFile,
+    json_extract(e.evidence_json,'$.sourceLine') sourceLine,
+    e.from_id eventName,
+    json_extract(c.evidence_json,'$.subscriptionLoopRegistrationStatus')
+      loopRegistrationStatus,
+    json_extract(c.evidence_json,'$.subscriptionLoopRegistrationCount')
+      loopRegistrationCount
+    FROM graph_edges e LEFT JOIN outbound_calls c
+      ON c.id=CAST(json_extract(e.evidence_json,'$.subscribeCallId') AS INTEGER)
+    WHERE e.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ${workspacePredicate('e')}
+      AND NOT EXISTS (SELECT 1 FROM graph_edges publication
+        WHERE publication.workspace_id=e.workspace_id
+          AND publication.generation=e.generation
+          AND publication.edge_type='HANDLER_EMITS_EVENT'
+          AND publication.to_kind='event'
+          AND publication.to_id=e.from_id)
+    ORDER BY repositoryName COLLATE BINARY,sourceFile COLLATE BINARY,
+      sourceLine,e.id LIMIT 5`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+}
+
+function unmatchedSubscriptionQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const row = db.prepare(`SELECT COUNT(*) siteCount,
+    SUM(CASE
+      WHEN json_extract(c.evidence_json,
+        '$.subscriptionLoopRegistrationStatus')='enumerated'
+        THEN CAST(json_extract(c.evidence_json,
+          '$.subscriptionLoopRegistrationCount') AS INTEGER)
+      WHEN json_extract(c.evidence_json,
+        '$.subscriptionLoopRegistrationStatus')='unresolved' THEN 0
+      ELSE 1 END) count,
+    SUM(CASE WHEN json_extract(c.evidence_json,
+      '$.subscriptionLoopRegistrationStatus')='unresolved'
+      THEN 1 ELSE 0 END) unknownMultiplicitySiteCount
+    FROM graph_edges e LEFT JOIN outbound_calls c
+      ON c.id=CAST(json_extract(e.evidence_json,'$.subscribeCallId') AS INTEGER)
+    WHERE e.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ${workspacePredicate('e')}
+      AND NOT EXISTS (SELECT 1 FROM graph_edges publication
+        WHERE publication.workspace_id=e.workspace_id
+          AND publication.generation=e.generation
+          AND publication.edge_type='HANDLER_EMITS_EVENT'
+          AND publication.to_kind='event'
+          AND publication.to_id=e.from_id)`).get(workspaceId, workspaceId);
+  const total = count(row?.count);
+  const siteCount = count(row?.siteCount);
+  return {
+    severity: siteCount > 0 ? 'warning' : 'info',
+    code: 'strict_event_subscription_without_publication_quality',
+    message: 'Event subscriptions without a matching publication',
+    unmatchedSubscriptionCount: total,
+    unmatchedSubscriptionSiteCount: siteCount,
+    unknownMultiplicitySiteCount: count(row?.unknownMultiplicitySiteCount),
+    examples: unmatchedSubscriptionRows(db, workspaceId),
+    exampleCount: siteCount,
+  };
+}
+
+function receiverProofQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const row = db.prepare(`SELECT COUNT(*) eventTotal,
+    SUM(CASE WHEN json_extract(c.evidence_json,
+      '$.receiverClassification')='cap_evidence' THEN 1 ELSE 0 END) proven,
+    SUM(CASE WHEN json_extract(c.evidence_json,
+      '$.receiverClassification')='name_fallback' THEN 1 ELSE 0 END)
+      nameFallback,
+    SUM(CASE WHEN json_extract(c.evidence_json,
+      '$.receiverClassification')='unproven' THEN 1 ELSE 0 END) unproven
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type IN ('async_emit','async_subscribe')
+      AND ${workspacePredicate('r')}`).get(workspaceId, workspaceId);
+  const buckets = db.prepare(`SELECT CASE
+      WHEN json_extract(c.evidence_json,
+        '$.receiverClassification')='name_fallback' THEN 'name_fallback'
+      WHEN json_extract(c.evidence_json,
+        '$.receiverClassification')='unproven'
+        THEN COALESCE(c.unresolved_reason,'unproven')
+      ELSE 'missing' END reason,COUNT(*) count
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type IN ('async_emit','async_subscribe')
+      AND ${workspacePredicate('r')}
+      AND json_extract(c.evidence_json,'$.receiverClassification')
+        <>'cap_evidence'
+    GROUP BY reason ORDER BY count DESC,reason COLLATE BINARY LIMIT 16`).all(
+    workspaceId, workspaceId,
+  );
+  const questionable = count(row?.nameFallback) + count(row?.unproven);
+  return {
+    severity: questionable > 0 ? 'warning' : 'info',
+    code: 'strict_event_receiver_classification_quality',
+    message: 'CAP event receiver proof aggregate',
+    eventTotal: count(row?.eventTotal),
+    proven: count(row?.proven),
+    nameFallback: count(row?.nameFallback),
+    unproven: count(row?.unproven),
+    questionable,
+    reasonBuckets: buckets,
+    examples: receiverProofExamples(db, workspaceId),
+    exampleCount: questionable,
+  };
+}
+
+function receiverProofExamples(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return db.prepare(`SELECT r.name repositoryName,c.call_type callType,
+    c.source_file sourceFile,c.source_line sourceLine,
+    json_extract(c.evidence_json,'$.receiverClassification')
+      receiverClassification,
+    c.unresolved_reason reason
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE c.call_type IN ('async_emit','async_subscribe')
+      AND ${workspacePredicate('r')}
+      AND json_extract(c.evidence_json,'$.receiverClassification')
+        <>'cap_evidence'
+    ORDER BY r.name COLLATE BINARY,c.source_file COLLATE BINARY,
+      c.source_line,c.id LIMIT 5`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+}
+
+function shapeEnvironmentExamples(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return db.prepare(`SELECT e.edge_type edgeType,e.from_id fromId,
+    e.to_kind toKind,e.to_id toId,
+    json_extract(e.evidence_json,
+      '$.eventEnvironmentResolution.status') environmentStatus,
+    json_extract(e.evidence_json,
+      '$.eventEnvironmentResolution.collisionCount') collisionCount
+    FROM graph_edges e WHERE ${workspacePredicate('e')}
+      AND (e.edge_type='EVENT_SHAPE_CANDIDATE_SUBSCRIBER'
+        OR json_extract(e.evidence_json,
+          '$.eventEnvironmentResolution.status')='ambiguous'
+        OR CAST(json_extract(e.evidence_json,
+          '$.eventEnvironmentResolution.collisionCount') AS INTEGER)>1)
+    ORDER BY e.edge_type COLLATE BINARY,e.from_id COLLATE BINARY,
+      e.to_id COLLATE BINARY,e.id LIMIT 5`).all(
+    workspaceId, workspaceId,
+  ) as Diagnostic[];
+}
+
+function shapeEnvironmentQuality(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic {
+  const row = db.prepare(`SELECT
+    SUM(CASE WHEN e.edge_type='EVENT_SHAPE_CANDIDATE_SUBSCRIBER'
+      THEN 1 ELSE 0 END) shapeCandidates,
+    SUM(CASE WHEN json_extract(e.evidence_json,
+      '$.eventEnvironmentResolution.status')='ambiguous'
+      OR CAST(json_extract(e.evidence_json,
+        '$.eventEnvironmentResolution.collisionCount') AS INTEGER)>1
+      THEN 1 ELSE 0 END) environmentAmbiguities
+    FROM graph_edges e WHERE ${workspacePredicate('e')}`).get(
+    workspaceId, workspaceId,
+  );
+  const shapes = count(row?.shapeCandidates);
+  const ambiguous = count(row?.environmentAmbiguities);
+  return {
+    severity: shapes + ambiguous > 0 ? 'warning' : 'info',
+    code: 'strict_event_shape_environment_quality',
+    message: 'Event skeleton candidate and environment ambiguity aggregate',
+    skeletonCandidateCount: shapes,
+    environmentBindingAmbiguityCount: ambiguous,
+    examples: shapeEnvironmentExamples(db, workspaceId),
+    exampleCount: shapes + ambiguous,
+  };
+}
+
+export function eventSurfaceQualityDiagnostics(
+  db: Db,
+  workspaceId?: number,
+): Diagnostic[] {
+  return [
+    eventNameResolutionQuality(db, workspaceId),
+    dynamicEventQuality(db, workspaceId),
+    unmatchedPublicationQuality(db, workspaceId),
+    unmatchedSubscriptionQuality(db, workspaceId),
+    receiverProofQuality(db, workspaceId),
+    shapeEnvironmentQuality(db, workspaceId),
+  ];
+}

package/src/cli/doctor.ts

@@ -11,6 +11,9 @@ import {
   packagePendingDiagnostics,
   symbolCallQuality,
 } from './doctor-package-resolution.js';
+import {
+  eventSurfaceQualityDiagnostics,
+} from './doctor-event-quality.js';
 export { linkUpgradeWarnings } from './doctor-lifecycle.js';
 
 type Diagnostic = Record<string, unknown>;
@@ -163,7 +166,7 @@ function parserQualityDiagnostics(db: Db, strict: boolean, options: DoctorOption
     externalHttpTargetQuality(db),
     odataInvocationResolutionQuality(db),
     ...jsonEvidenceQuality(db),
-    eventReceiverQuality(db),
+    ...eventSurfaceQualityDiagnostics(db, options.workspaceId),
     graphDynamicFlagQuality(db),
     symbol,
     dbq,
@@ -202,11 +205,6 @@ function outboundOwnershipQuality(db: Db): Diagnostic {
   return { severity: ratio > 0.01 ? 'warning' : 'info', code: 'strict_outbound_source_ownership_quality', message: 'Outbound call source-symbol ownership aggregate', total, withoutOwnership: without, withoutOwnershipRatio: ratio, withoutOwnershipRatioThreshold: 0.01, ownerlessByType: byType, ownerlessExamples: examples };
 }
 
-function eventReceiverQuality(db: Db): Diagnostic {
-  const row = db.prepare("SELECT SUM(CASE WHEN call_type IN ('async_emit','async_subscribe') THEN 1 ELSE 0 END) eventTotal, SUM(CASE WHEN call_type IN ('async_emit','async_subscribe') AND (json_extract(evidence_json,'$.receiverClassification') IS NULL OR json_extract(evidence_json,'$.receiverClassification') <> 'cap_evidence') THEN 1 ELSE 0 END) questionable FROM outbound_calls").get() as Record<string, unknown>;
-  return { severity: Number(row.questionable ?? 0) > 0 ? 'warning' : 'info', code: 'strict_event_receiver_classification_quality', message: 'CAP event receiver classification aggregate', eventTotal: Number(row.eventTotal ?? 0), questionable: Number(row.questionable ?? 0) };
-}
-
 function graphDynamicFlagQuality(db: Db): Diagnostic {
   const row = db.prepare("SELECT COUNT(*) count FROM graph_edges WHERE status='terminal' AND is_dynamic=1").get() as Record<string, unknown>;
   return { severity: Number(row.count ?? 0) > 0 ? 'warning' : 'info', code: 'strict_graph_dynamic_flag_consistency', message: 'Graph dynamic flag consistency aggregate', dynamicTerminalEdges: Number(row.count ?? 0) };

package/src/cli.ts

@@ -298,7 +298,7 @@ function registerLinkCommand(program: Command): void {
           const r = linkWorkspace(db, workspaceId);
           const upgradeWarnings = linkUpgradeWarnings(db, workspaceId);
           writeStdout(
-            `${upgradeWarnings.length ? `Warnings: ${upgradeWarnings.map((item) => String(item.code)).join(', ')}. Run service-flow doctor --strict for remediation.\n` : ''}Linked ${r.edgeCount} edges: ${r.remoteResolvedCount} remote operation calls resolved, ${r.localResolvedCount} local operation calls resolved, ${r.unresolvedCount} unresolved operation calls, ${r.ambiguousCount} ambiguous operation calls, ${r.dynamicCount} dynamic operation calls, ${r.terminalCount} terminal call edges, ${r.dependencyResolvedCount} dependency resolved, ${r.dependencyAmbiguousCount} dependency ambiguous, ${r.implementationResolvedCount} implementation resolved, ${r.implementationAmbiguousCount} implementation ambiguous, ${r.implementationUnresolvedCount} implementation unresolved, ${r.subscriptionHandlerResolvedCount} subscription handlers resolved, ${r.subscriptionHandlerAmbiguousCount} subscription handlers ambiguous, ${r.subscriptionHandlerUnresolvedCount} subscription handlers unresolved, ${r.subscriptionHandlerMissingAssociationCount} subscription handler associations missing\n`,
+            `${upgradeWarnings.length ? `Warnings: ${upgradeWarnings.map((item) => String(item.code)).join(', ')}. Run service-flow doctor --strict for remediation.\n` : ''}Linked ${r.edgeCount} edges: ${r.remoteResolvedCount} remote operation calls resolved, ${r.localResolvedCount} local operation calls resolved, ${r.unresolvedCount} unresolved operation calls, ${r.ambiguousCount} ambiguous operation calls, ${r.dynamicCount} dynamic operation calls, ${r.terminalCount} terminal call edges, ${r.dependencyResolvedCount} dependency resolved, ${r.dependencyAmbiguousCount} dependency ambiguous, ${r.implementationResolvedCount} implementation resolved, ${r.implementationAmbiguousCount} implementation ambiguous, ${r.implementationUnresolvedCount} implementation unresolved, ${r.subscriptionHandlerResolvedCount} subscription handlers resolved, ${r.subscriptionHandlerAmbiguousCount} subscription handlers ambiguous, ${r.subscriptionHandlerUnresolvedCount} subscription handlers unresolved, ${r.subscriptionHandlerMissingAssociationCount} subscription handler associations missing, ${r.eventShapeCandidateCount} event shape candidates\n`,
           );
         }).catch(fail),
     );

package/src/db/call-fact-repository.ts

@@ -400,11 +400,12 @@ export function insertCalls(
 function outboundCallInsertStatement(db: Db): Statement {
   return db.prepare(`INSERT INTO outbound_calls(
     repo_id,source_symbol_id,call_type,method,operation_path_expr,query_entity,
-    event_name_expr,payload_summary,source_file,source_line,call_site_start_offset,
+    event_name_expr,event_skeleton_signature,event_skeleton_json,
+    payload_summary,source_file,source_line,call_site_start_offset,
     call_site_end_offset,confidence,unresolved_reason,local_service_name,
     local_service_lookup,alias_chain_json,evidence_json,external_target_kind,
     external_target_id,external_target_label,external_target_dynamic,service_binding_id
-  ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
+  ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
 }
 
 function insertOutboundCall(
@@ -424,7 +425,9 @@ function insertOutboundCall(
   stmt.run(
     repoId, sourceSymbolId,
     call.callType, call.method, call.operationPathExpr, call.queryEntity,
-    call.eventNameExpr, call.payloadSummary, call.sourceFile, call.sourceLine,
+    call.eventNameExpr, call.eventSkeleton?.signature ?? null,
+    call.eventSkeleton ? JSON.stringify(call.eventSkeleton) : null,
+    call.payloadSummary, call.sourceFile, call.sourceLine,
     call.callSiteStartOffset, call.callSiteEndOffset, call.confidence,
     call.unresolvedReason,
     call.localServiceName, call.localServiceLookup,

package/src/db/current-fact-semantics.ts

@@ -10,9 +10,8 @@ import {
 import {
   invalidBindingFactCategories,
 } from './binding-fact-semantics.js';
-import {
-  invalidSymbolFactCategories,
-} from './symbol-call-semantics.js';
+import { invalidSymbolFactCategories } from './symbol-call-semantics.js';
+import { invalidEventFactCategories } from './event-fact-semantics.js';
 
 export type PackageFactPhase = 'pre_package' | 'terminal';
 
@@ -262,7 +261,7 @@ function eventNameCategories(
   db: Db,
   workspaceId?: number,
 ): FactSemanticCategoryCount[] {
-  const invalid = count(db, `SELECT COUNT(*) count
+  const invalidName = count(db, `SELECT COUNT(*) count
     FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
     WHERE ${currentRepositoryPredicate()}
       AND fact.call_type IN ('async_emit','async_subscribe')
@@ -278,7 +277,7 @@ function eventNameCategories(
       fact.call_site_end_offset HAVING COUNT(*)<>1
   )`, workspaceId);
   return [
-    ...category('event_name_invalid', invalid),
+    ...category('event_name_invalid', invalidName),
     ...category('async_subscription_site_duplicate', duplicate),
   ];
 }
@@ -686,6 +685,7 @@ export function invalidFactSemanticCategories(
     ...callSpanCategories(db, workspaceId),
     ...duplicateSymbolCallCategories(db, workspaceId),
     ...eventNameCategories(db, workspaceId),
+    ...invalidEventFactCategories(db, workspaceId, phase),
     ...ownerCategories(db, workspaceId),
     ...bindingCategories(db, workspaceId),
     ...invalidBindingFactCategories(db, workspaceId),