@saptools/service-flow 0.1.67 → 0.1.69

package/src/trace/002-trace-diagnostics.ts

@@ -7,7 +7,7 @@ export function loadTraceDiagnostics(
   workspaceId?: number,
 ): Array<Record<string, unknown>> {
   if (repoId === undefined && !includeWorkspaceDiagnostics) return [];
-  return db.prepare(`SELECT d.repo_id repoId,d.severity,d.code,d.message,
+  const diagnostics = db.prepare(`SELECT d.repo_id repoId,d.severity,d.code,d.message,
       d.source_file sourceFile,d.source_line sourceLine
     FROM diagnostics d LEFT JOIN repositories r ON r.id=d.repo_id
     WHERE (? IS NULL OR d.repo_id=?)
@@ -18,6 +18,41 @@ export function loadTraceDiagnostics(
       ) as Array<
         Record<string, unknown>
       >;
+  const pending = packagePendingCount(
+    db, repoId, includeWorkspaceDiagnostics, workspaceId,
+  );
+  if (pending > 0) diagnostics.unshift(packagePendingDiagnostic(pending));
+  return diagnostics;
+}
+
+function packagePendingCount(
+  db: Db,
+  repoId: number | undefined,
+  includeWorkspace: boolean,
+  workspaceId: number | undefined,
+): number {
+  const row = db.prepare(`SELECT COUNT(*) count FROM symbol_calls sc
+    JOIN repositories r ON r.id=sc.repo_id
+    WHERE sc.status='unresolved' AND sc.callee_symbol_id IS NULL
+      AND sc.unresolved_reason='package_resolution_pending'
+      AND (?=1 OR sc.repo_id=?)
+      AND (? IS NULL OR r.workspace_id=?)`).get(
+        includeWorkspace ? 1 : 0, repoId, workspaceId, workspaceId,
+      );
+  return Number(row?.count ?? 0);
+}
+
+function packagePendingDiagnostic(count: number): Record<string, unknown> {
+  return {
+    severity: 'warning',
+    code: 'package_import_resolution_pending',
+    message: 'Package-import facts await workspace linking.',
+    packageResolutionState: 'pre_link_pending',
+    pendingPackageImportCount: count,
+    graphState: 'stale',
+    requiredAction: 'relink',
+    remediation: 'Run service-flow link --force for this workspace.',
+  };
 }
 
 export function prependTraceDiagnostic(

package/src/trace/007-implementation-start-diagnostic.ts

@@ -15,6 +15,7 @@ export function implementationStartDiagnostic(
     message: `Indexed operation matched but implementation edge is ${String(
       edge.status ?? 'unresolved',
     )}`,
+    selectorKind: 'operation',
     resolutionStage: 'implementation',
     resolutionStatus: edge.status === 'ambiguous'
       ? 'ambiguous_implementation'

package/src/trace/011-event-subscriber-traversal.ts

@@ -1,5 +1,10 @@
 import type { Db } from '../db/connection.js';
 import {
+  matchRuntimeTemplate,
+  substituteVariables,
+} from '../linker/dynamic-edge-resolver.js';
+import {
+  compareBinary,
   type TraversalScopeScheduler,
   type TraversalScopeState,
 } from './010-traversal-scope.js';
@@ -53,6 +58,8 @@ export interface EventSubscriberTransition {
   candidateCount: number;
   symbolCallUnresolvedReason?: string;
   omittedSymbolCallUnresolvedReasonCharacterCount?: number;
+  matchStrategy?: string;
+  dispatchCertainty?: string;
   handler?: EventSubscriberSymbolTarget;
 }
 
@@ -60,6 +67,7 @@ export interface EventSubscriberTransitionQuery {
   workspaceId: number;
   graphGeneration: number;
   eventName: string;
+  vars?: Record<string, string>;
 }
 
 export type EventBodyExpansion =
@@ -156,8 +164,8 @@ export function eventTransitionEvidence(
     subscribeCallId: transition.subscribeCallId,
     symbolCallId: transition.symbolCallId,
     eventName: transition.eventName,
-    matchStrategy: 'workspace_exact_event_name',
-    dispatchCertainty: 'static_name_only',
+    matchStrategy: transition.matchStrategy ?? 'workspace_exact_event_name',
+    dispatchCertainty: transition.dispatchCertainty ?? 'static_name_only',
     associationBasis: transition.associationBasis,
     dispatchScope: transition.dispatchScope,
     roleSiteMatchCount: transition.roleSiteMatchCount,
@@ -194,7 +202,8 @@ export function loadEventSubscriberTransitions(
   query: EventSubscriberTransitionQuery,
 ): EventSubscriberTransition[] {
   const rows = db.prepare(`SELECT ge.id graphEdgeId,ge.generation graphGeneration,
-      ge.from_id eventName,ge.status,ge.to_kind targetKind,ge.to_id targetId,
+      ge.from_kind fromKind,ge.from_id eventName,ge.status,
+      ge.to_kind targetKind,ge.to_id targetId,
       ge.confidence,ge.unresolved_reason unresolvedReason,ge.evidence_json evidenceJson,
       subscribe.id subscribeCallId,subscribe.repo_id subscriptionRepoId,
       subscribe.source_file sourceFile,subscribe.source_line sourceLine,
@@ -218,19 +227,100 @@ export function loadEventSubscriberTransitions(
     LEFT JOIN repositories handler_repo
       ON handler_repo.id=handler.repo_id AND handler_repo.workspace_id=ge.workspace_id
     WHERE ge.workspace_id=? AND ge.generation=?
-      AND ge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY' AND ge.from_kind='event'
-      AND ge.from_id COLLATE BINARY=? COLLATE BINARY
+      AND ge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ge.from_kind IN ('event','event_candidate')
     ORDER BY COALESCE(subscription_repo.name,'') COLLATE BINARY,
       COALESCE(subscription_repo.id,0),COALESCE(subscribe.source_file,'') COLLATE BINARY,
       subscribe.call_site_start_offset,subscribe.call_site_end_offset,ge.id`).all(
-    query.workspaceId, query.graphGeneration, query.eventName,
+    query.workspaceId, query.graphGeneration,
   );
-  return rows.flatMap((row) => {
-    const transition = transitionFromRow(row);
+  return rows.flatMap((raw) => {
+    const row = eventRowForQuery(raw, query);
+    const transition = row ? transitionFromRow(row) : undefined;
     return transition ? [transition] : [];
   });
 }
 
+function eventRowForQuery(
+  row: Record<string, unknown>,
+  query: EventSubscriberTransitionQuery,
+): Record<string, unknown> | undefined {
+  const variables = query.vars;
+  if (variables === undefined) return exactPersistedEventRow(row, query);
+  const evidence = parseEvidence(row.evidenceJson);
+  const resolution = isRecord(evidence.eventTemplateResolution)
+    ? evidence.eventTemplateResolution : {};
+  if (typeof resolution.original !== 'string')
+    return exactPersistedEventRow(row, query);
+  return runtimeMatchedEventRow(
+    row, query, evidence, resolution.original, variables,
+  );
+}
+
+function exactPersistedEventRow(
+  row: Record<string, unknown>,
+  query: EventSubscriberTransitionQuery,
+): Record<string, unknown> | undefined {
+  return row.fromKind === 'event' && row.eventName === query.eventName
+    ? row : undefined;
+}
+
+function runtimeMatchedEventRow(
+  row: Record<string, unknown>,
+  query: EventSubscriberTransitionQuery,
+  evidence: Record<string, unknown>,
+  template: string,
+  variables: Record<string, string>,
+): Record<string, unknown> | undefined {
+  const substitution = substituteVariables(template, variables);
+  if (substitution.missing.length > 0
+    || substitution.effective !== query.eventName) return undefined;
+  const resolvedAssociation = evidence.associationStatus === 'resolved';
+  return {
+    ...row,
+    eventName: query.eventName,
+    status: typeof evidence.associationStatus === 'string'
+      ? evidence.associationStatus : row.status,
+    unresolvedReason: resolvedAssociation ? null : row.unresolvedReason,
+    evidenceJson: JSON.stringify({
+      ...evidence,
+      eventSubscriptionRuntimeSubstitution: substitution,
+      matchStrategy: 'workspace_exact_event_name_after_runtime_substitution',
+      dispatchCertainty: 'runtime_variables_exact',
+    }),
+  };
+}
+
+export function eventSubscriberMissingVariables(
+  db: Db,
+  query: EventSubscriberTransitionQuery,
+): string[] {
+  if (query.vars === undefined) return [];
+  const variables = query.vars;
+  const rows = db.prepare(`SELECT ge.from_id eventName,
+    ge.evidence_json evidenceJson FROM graph_edges ge
+    WHERE ge.workspace_id=? AND ge.generation=?
+      AND ge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ge.from_kind='event_candidate'`).all(
+    query.workspaceId, query.graphGeneration,
+  );
+  const missing = rows.flatMap((row) => {
+    const evidence = parseEvidence(row.evidenceJson);
+    const resolution = isRecord(evidence.eventTemplateResolution)
+      ? evidence.eventTemplateResolution : {};
+    const template = typeof resolution.original === 'string'
+      ? resolution.original : undefined;
+    if (!template) return [];
+    const substitution = substituteVariables(template, variables);
+    if (substitution.missing.length === 0
+      || matchRuntimeTemplate(
+        substitution.effective, query.eventName,
+      ) === undefined) return [];
+    return substitution.missing;
+  });
+  return [...new Set(missing)].sort(compareBinary);
+}
+
 function transitionFromRow(
   row: Record<string, unknown>,
 ): EventSubscriberTransition | undefined {
@@ -290,6 +380,8 @@ function associationEvidence(
     omittedSymbolCallUnresolvedReasonCharacterCount: symbolCallUnresolvedReason
       ? nonNegativeCount(evidence.omittedSymbolCallUnresolvedReasonCharacterCount)
       : undefined,
+    matchStrategy: stringValue(evidence.matchStrategy),
+    dispatchCertainty: stringValue(evidence.dispatchCertainty),
   };
 }
 

package/src/trace/013-trace-root-scopes.ts

@@ -253,12 +253,11 @@ function hasExactDispatch(db: Db, calls: RootCallRow[]): boolean {
           AND subscriber.generation=emitted.generation
           AND subscriber.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
           AND subscriber.from_kind='event'
-          AND subscriber.from_id COLLATE BINARY=? COLLATE BINARY)
+          AND subscriber.from_id COLLATE BINARY=emitted.to_id COLLATE BINARY)
     LIMIT 1`);
   return calls.some((call) => call.callType === 'async_emit'
-    && typeof call.eventName === 'string'
     && Boolean(match.get(call.workspaceId, call.graphGeneration,
-      String(call.id), call.eventName)));
+      String(call.id))));
 }
 
 function workspaceAmbiguityDiagnostic(db: Db): Record<string, unknown> {

package/src/trace/014-compact-contract.ts

@@ -82,6 +82,7 @@ export interface CompactDecisionInput {
   implementationStrategy?: string;
   implementationGuided?: boolean;
   implementationContextual?: boolean;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
   reasonCode?: string;
   eventMatchStrategy?: string;
   dispatchCertainty?: string;
@@ -225,6 +226,7 @@ export interface CompactDecisionV1 {
   implementationStrategy?: string;
   implementationGuided?: boolean;
   implementationContextual?: boolean;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
   eventMatchStrategy?: string;
   dispatchCertainty?: string;
   eventSubscriptionCount?: number;
@@ -247,6 +249,10 @@ export interface CompactEdgeDetailsV1 {
 
 export interface CompactDiagnosticDetailsV1 {
   reasonCode?: string;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
+  selectorKind?: string;
+  selectorSuggestions?: CompactReferenceGroupV1;
+  invalidFactCategories?: CompactReferenceGroupV1;
   missingVariableNames?: string[];
   missingVariableCount?: number;
   shownMissingVariableCount?: number;

package/src/trace/015-trace-edge-recorder.ts

@@ -8,6 +8,12 @@ import type {
   CompactStatus,
   CompactTraceObserver,
 } from './014-compact-contract.js';
+import { implementationHintSuggestionProjection } from
+  './implementation-hints.js';
+import {
+  isSafeCompactReferenceName,
+  projectCompactReferenceGroup,
+} from './021-compact-decision-normalization.js';
 
 export interface TraceEdgeSemantics {
   source: CompactSemanticEndpoint;
@@ -111,8 +117,7 @@ export function semanticGraphTarget(
 ): CompactSemanticEndpoint {
   if (row.to_kind === 'event') return {
     kind: 'event', workspaceId,
-    eventName: typeof call.event_name_expr === 'string'
-      ? call.event_name_expr : row.to_id,
+    eventName: row.to_id,
   };
   const id = positiveNumber(row.to_id);
   if (row.to_kind === 'operation')
@@ -198,7 +203,7 @@ export function compactDecisionFromEvidence(
   const authoritativeMissingCount = finiteNumber(
     dynamic.missingVariableCount ?? evidence.missingVariableCount,
   );
-  return {
+  const decision: CompactDecisionInput = {
     effectiveResolutionStatus: stringValue(effective.status),
     effectiveTarget: targetSummary(effective),
     persistedResolutionStatus: stringValue(persisted.status),
@@ -221,7 +226,7 @@ export function compactDecisionFromEvidence(
     implementationGuided: booleanValue(implementation.guided),
     implementationContextual: booleanValue(
       evidence.contextualImplementationSelected),
-    reasonCode: stringValue(evidence.reasonCode ?? evidence.cycleReason),
+    reasonCode: compactEvidenceReasonCode(evidence),
     eventMatchStrategy: stringValue(evidence.matchStrategy),
     dispatchCertainty: stringValue(evidence.dispatchCertainty),
     associationStatus: stringValue(evidence.associationStatus),
@@ -233,6 +238,7 @@ export function compactDecisionFromEvidence(
     bodyExpansion: stringValue(evidence.bodyExpansion),
     ...overrides,
   };
+  return decisionWithTiedCandidates(evidence, decision);
 }
 
 export function compactRefs(
@@ -334,3 +340,54 @@ function firstNumber(...values: unknown[]): number | undefined {
   }
   return undefined;
 }
+
+export function compactEvidenceReasonCode(
+  evidence: Record<string, unknown>,
+): string | undefined {
+  return stringValue(evidence.reasonCode ?? evidence.cycleReason)
+    ?? parserWarningReason(evidence.parserWarning);
+}
+
+function parserWarningReason(value: unknown): string | undefined {
+  const warning = recordValue(value);
+  const code = stringValue(warning.code);
+  if (code && code !== 'parser_warning') return code;
+  return stringValue(warning.message);
+}
+
+function tiedCandidateRepositoryGroup(
+  evidence: Record<string, unknown>,
+  decision: CompactDecisionInput,
+): CompactDecisionInput['tiedCandidateRepos'] {
+  if (decision.effectiveResolutionStatus !== 'ambiguous'
+    || (decision.candidateCount ?? 0) <= 1) return undefined;
+  const persisted = Array.isArray(evidence.implementationHintSuggestions)
+    ? evidence.implementationHintSuggestions.filter(
+        (value): value is Record<string, unknown> =>
+          Boolean(value && typeof value === 'object' && !Array.isArray(value)),
+      )
+    : [];
+  const projection = persisted.length > 0 ? {
+    suggestions: persisted,
+    suggestionCount: finiteNumber(
+      evidence.implementationHintSuggestionCount,
+    ) ?? persisted.length,
+  } : implementationHintSuggestionProjection(
+    evidence, Number.MAX_SAFE_INTEGER,
+  );
+  const repos = projection.suggestions.flatMap((suggestion) =>
+    typeof suggestion.implementationRepo === 'string'
+      ? [suggestion.implementationRepo] : []);
+  const group = projectCompactReferenceGroup(
+    repos, projection.suggestionCount, isSafeCompactReferenceName,
+  );
+  return group && group.total > 1 ? group : undefined;
+}
+
+function decisionWithTiedCandidates(
+  evidence: Record<string, unknown>,
+  decision: CompactDecisionInput,
+): CompactDecisionInput {
+  const tiedCandidateRepos = tiedCandidateRepositoryGroup(evidence, decision);
+  return tiedCandidateRepos ? { ...decision, tiedCandidateRepos } : decision;
+}

package/src/trace/016-compact-projector.ts

@@ -20,10 +20,13 @@ import {
 } from './014-compact-contract.js';
 import {
   compactCompleteness, compactSafeCode, compactStatusCounts, compactStatusTotal,
-  projectCompactDecision, projectCompactDecisionTarget, projectCompactDiagnostics,
+  projectCompactDecisionTarget, projectCompactDiagnostics,
   projectCompactQuery, projectCompactStart,
-  removeEquivalentCompactPersistedDecision,
 } from './020-compact-field-projection.js';
+import {
+  projectObservationDecision,
+  type CompactDecisionNode,
+} from './024-compact-observation-decision.js';
 
 const REFERENCE_LIMIT = 5;
 
@@ -92,29 +95,24 @@ function observationDecision(
   input: CompactEdgeObservation,
   target: ResolvedNode,
 ): CompactDecisionV1 {
-  const decision = projectCompactDecision(input.decision);
-  if (decision.effectiveResolutionStatus && target.decisionTarget)
-    decision.effectiveTarget = target.decisionTarget;
-  if (decision.persistedResolutionStatus && input.decision?.persistedTarget) {
-    const persisted = persistedDecisionTarget(db, input.decision.persistedTarget);
-    if (persisted) decision.persistedTarget = persisted;
-  }
-  removeEquivalentCompactPersistedDecision(decision);
-  return decision;
+  return projectObservationDecision(
+    input, target, (value) => decisionInputNode(db, value),
+  );
 }
 
-function persistedDecisionTarget(
+function decisionInputNode(
   db: Db,
   target: CompactDecisionTargetInput,
-): string | undefined {
+): CompactDecisionNode {
   const numeric = numericId(target.id);
   if (target.kind === 'operation' && numeric !== undefined)
-    return operationNode(db, numeric)?.decisionTarget;
+    return operationNode(db, numeric) ?? {};
   if (target.kind === 'symbol' && numeric !== undefined)
-    return symbolNode(db, numeric)?.decisionTarget;
+    return symbolNode(db, numeric) ?? {};
   if (target.kind === 'handler_method' && numeric !== undefined)
-    return handlerNode(db, numeric)?.decisionTarget;
-  return projectCompactDecisionTarget(target.kind, target.id);
+    return handlerNode(db, numeric) ?? {};
+  const decisionTarget = projectCompactDecisionTarget(target.kind, target.id);
+  return { key: decisionTarget, decisionTarget, projectedIdentity: true };
 }
 
 function resolveEndpoint(

package/src/trace/019-trace-edge-semantics.ts

@@ -2,6 +2,7 @@ import type { TraceEdge } from '../types.js';
 import type { CompactSemanticEndpoint, CompactStatus } from './014-compact-contract.js';
 import {
   compactDecisionFromEvidence,
+  compactEvidenceReasonCode,
   compactEventStatus,
   compactGraphStatus,
   compactRefs,
@@ -157,11 +158,11 @@ export function recordOutboundObservation(
     source, target,
     status: compactGraphStatus(input.row, input.evidence,
       input.unresolvedReason, input.dynamicMode),
-    decision: compactDecisionFromEvidence(input.evidence, {
-      reasonCode: input.unresolvedReason
-        ? safeReasonCode(input.evidence.reasonCode, 'outbound_target_unresolved')
-        : undefined,
-    }),
+    decision: compactDecisionFromEvidence(input.evidence,
+      input.unresolvedReason ? {
+        reasonCode: compactEvidenceReasonCode(input.evidence)
+          ?? 'outbound_target_unresolved',
+      } : {}),
     refs: compactRefs({
       graphEdgeId: positiveId(input.evidence.persistedGraphEdgeId),
       outboundCallId: input.call.id,
@@ -295,11 +296,6 @@ function eventSite(
     endOffset: plan.transition.callSiteEndOffset });
 }
 
-function safeReasonCode(value: unknown, fallback: string): string {
-  return typeof value === 'string' && /^[a-z][a-z0-9_.-]{0,79}$/.test(value)
-    ? value : fallback;
-}
-
 function positiveId(value: unknown): number | string | undefined {
   if (typeof value === 'number') return Number.isFinite(value) && value > 0
     ? value : undefined;