@saptools/service-flow 0.1.68 → 0.1.69

package/src/trace/021-compact-decision-normalization.ts

@@ -1,11 +1,14 @@
 import { compareBinary } from './010-traversal-scope.js';
 import type {
   CompactDecisionV1,
+  CompactReferenceGroupV1,
   CompactStatus,
 } from './014-compact-contract.js';
 
 export const COMPACT_MISSING_NAME_LIMIT = 8;
 export const COMPACT_MISSING_NAME_MAX_LENGTH = 160;
+export const COMPACT_REFERENCE_VALUE_LIMIT = 5;
+const COMPACT_REFERENCE_VALUE_MAX_LENGTH = 240;
 
 export interface CompactMissingNameProjection {
   readonly names: string[];
@@ -23,11 +26,17 @@ export function projectCompactMissingNames(
   values: readonly string[] | undefined,
   authoritativeCount: unknown,
 ): CompactMissingNameProjection {
-  const raw = [...new Set((values ?? [])
-    .map((value) => value.trim())
-    .filter(Boolean))]
-    .sort(compareBinary);
-  const safe = raw.filter(isSafeCompactMissingName);
+  const candidates = new Map<string, boolean>();
+  for (const value of values ?? []) {
+    const normalized = value.trim();
+    if (!normalized) continue;
+    candidates.set(
+      normalized,
+      (candidates.get(normalized) ?? true) && isSafeCompactMissingName(value),
+    );
+  }
+  const raw = [...candidates.keys()].sort(compareBinary);
+  const safe = raw.filter((name) => candidates.get(name) === true);
   const names = safe.slice(0, COMPACT_MISSING_NAME_LIMIT);
   const total = Math.max(compactCount(authoritativeCount), raw.length);
   return {
@@ -37,25 +46,58 @@ export function projectCompactMissingNames(
 }
 
 export function isSafeCompactMissingName(value: string): boolean {
+  if (hasControlCharacter(value)) return false;
   const normalized = value.trim();
   return normalized.length > 0
     && normalized.length <= COMPACT_MISSING_NAME_MAX_LENGTH
-    && !hasControlCharacter(normalized)
     && safeMissingName.test(normalized);
 }
 
+export function projectCompactReferenceGroup(
+  values: readonly string[] | undefined,
+  authoritativeCount: unknown,
+  isSafe: (value: string) => boolean,
+): CompactReferenceGroupV1 | undefined {
+  const candidates = normalizedReferenceValues(values, isSafe);
+  const unique = [...candidates.keys()].sort(compareBinary);
+  const safe = unique.filter((value) => candidates.get(value) === true);
+  const shown = safe.slice(0, COMPACT_REFERENCE_VALUE_LIMIT);
+  const total = Math.max(compactCount(authoritativeCount), unique.length);
+  if (total === 0) return undefined;
+  return {
+    values: shown,
+    total,
+    shown: shown.length,
+    omitted: Math.max(0, total - shown.length),
+  };
+}
+
+export function isSafeCompactReferenceName(value: string): boolean {
+  if (!safeReferenceText(value, 160)) return false;
+  return /^[@A-Za-z0-9_$][@A-Za-z0-9_$./:-]*$/.test(value.trim());
+}
+
+export function isSafeCompactSelectorSuggestion(value: string): boolean {
+  if (!safeReferenceText(value, COMPACT_REFERENCE_VALUE_MAX_LENGTH))
+    return false;
+  return /^(?:--(?:repo|service|operation|path|handler) [@A-Za-z0-9_$./:-]+)(?: --(?:repo|service|operation|path|handler) [@A-Za-z0-9_$./:-]+)*$/
+    .test(value.trim());
+}
+
 export function normalizeCompactDecisionEquivalence(
   decision: CompactDecisionV1,
   status: CompactStatus,
   canonicalTarget: string | undefined,
   targetIdentityEqual = false,
   persistedIdentityEqual = false,
+  rawPersistedStatus?: string,
 ): void {
+  if (decision.effectiveResolutionStatus === status)
+    delete decision.effectiveResolutionStatus;
   removeEquivalentPersistedDecision(
     decision, status, canonicalTarget, persistedIdentityEqual,
+    rawPersistedStatus,
   );
-  if (decision.effectiveResolutionStatus === status)
-    delete decision.effectiveResolutionStatus;
   if (targetIdentityEqual && canonicalTarget !== undefined
     && decision.effectiveTarget === canonicalTarget)
     delete decision.effectiveTarget;
@@ -77,9 +119,10 @@ function removeEquivalentPersistedDecision(
   status: CompactStatus,
   canonicalTarget: string | undefined,
   identityEqual: boolean,
+  rawPersistedStatus: string | undefined,
 ): void {
   if (!identityEqual
-    || decision.persistedResolutionStatus !== status
+    || rawPersistedStatus !== status
     || (decision.effectiveResolutionStatus !== undefined
       && decision.persistedResolutionStatus
         !== decision.effectiveResolutionStatus))
@@ -96,6 +139,29 @@ function compactCount(value: unknown): number {
     ? Math.max(0, Math.floor(value)) : 0;
 }
 
+function normalizedReferenceValues(
+  values: readonly string[] | undefined,
+  isSafe: (value: string) => boolean,
+): Map<string, boolean> {
+  const unique = new Map<string, boolean>();
+  for (const raw of values ?? []) {
+    const value = raw.trim();
+    if (!value) continue;
+    unique.set(value, (unique.get(value) ?? true) && isSafe(raw));
+  }
+  return unique;
+}
+
+function safeReferenceText(value: string, maxLength: number): boolean {
+  if (hasControlCharacter(value)) return false;
+  const normalized = value.trim();
+  return normalized.length > 0
+    && normalized.length <= maxLength
+    && !/^[a-z]+:\/\//i.test(normalized)
+    && !/(?:^|[^A-Za-z0-9])(?:authorization|bearer|credential|destination|password|secret|token)(?:$|[^A-Za-z0-9])/i
+      .test(normalized);
+}
+
 function hasControlCharacter(value: string): boolean {
   for (let index = 0; index < value.length; index += 1) {
     const code = value.charCodeAt(index);

package/src/trace/024-compact-observation-decision.ts

@@ -10,6 +10,7 @@ import { normalizeCompactDecisionEquivalence } from
 export interface CompactDecisionNode {
   key?: string;
   decisionTarget?: string;
+  projectedIdentity?: boolean;
 }
 
 function resolvedNode(
@@ -40,7 +41,10 @@ function sameCanonicalNode(
   left: CompactDecisionNode | undefined,
   right: CompactDecisionNode,
 ): boolean {
-  return left?.key !== undefined && left.key === right.key;
+  if (left?.key === undefined) return false;
+  return left.projectedIdentity === true
+    ? left.key === right.decisionTarget
+    : left.key === right.key;
 }
 
 function persistedCanonical(
@@ -49,7 +53,7 @@ function persistedCanonical(
   target: CompactDecisionNode,
 ): boolean {
   if (!sameCanonicalNode(persisted, target)) return false;
-  return effective?.key === undefined || effective.key === target.key;
+  return effective?.key === undefined || sameCanonicalNode(effective, target);
 }
 
 export function projectObservationDecision(
@@ -71,6 +75,7 @@ export function projectObservationDecision(
     target.decisionTarget,
     sameCanonicalNode(effective, target),
     persistedCanonical(persisted, effective, target),
+    source?.persistedResolutionStatus,
   );
   return decision;
 }

package/src/trace/026-trace-start-scope.ts

@@ -150,6 +150,7 @@ function unresolvedOperationStart(
       severity: 'warning',
       code: 'trace_start_implementation_unresolved',
       message: 'Indexed operation matched but no implementation candidate exists',
+      selectorKind: 'operation',
       resolutionStage: 'implementation',
       resolutionStatus: 'operation_without_implementation',
     }],

package/src/trace/027-trace-scope-execution.ts

@@ -17,10 +17,7 @@ import {
   TraversalScopeScheduler,
   type TraversalScopeState,
 } from './010-traversal-scope.js';
-import {
-  planEventSubscriberTransitions,
-  type PlannedEventSubscriberTransition,
-} from './011-event-subscriber-traversal.js';
+import type { PlannedEventSubscriberTransition } from './011-event-subscriber-traversal.js';
 import {
   graphForCalls,
   operationNode,
@@ -36,7 +33,6 @@ import {
 import type { CompactSemanticEndpoint } from './014-compact-contract.js';
 import { TraceEdgeRecorder } from './015-trace-edge-recorder.js';
 import {
-  contextForSymbolCall,
   knownBindingsForCalls,
   knownBindingsForScope,
   parseTraceEvidence,
@@ -53,6 +49,8 @@ import {
 import { outboundScopeSymbolIds } from './023-nested-event-scopes.js';
 import type { ImplementationHintOptions } from './025-trace-implementation-scope.js';
 import { processOperationTarget } from './028-trace-operation-execution.js';
+import { runtimeEventResolution, runtimeEventSubscriberPlans } from './030-event-runtime-resolution.js';
+import { planLocalCallExpansion } from './031-local-call-expansion.js';
 
 export interface CallRow extends Record<string, unknown> {
   id: number;
@@ -226,20 +224,10 @@ function processLocalCall(
   bindings: Map<string, ContextBinding>,
   row: Record<string, unknown>,
 ): void {
-  if (!row.callee_symbol_id) return;
-  const symbolId = Number(row.callee_symbol_id);
-  const symbols = new Set([symbolId]);
-  const files = new Set([String(row.calleeFile)]);
-  const repoId = Number(row.calleeRepoId);
-  const context = contextForSymbolCall(runtime.db, row, bindings);
-  const scheduling = runtime.scheduler.schedule({
-    workspaceId: runtime.workspaceId,
-    repoId,
-    files,
-    symbolIds: symbols,
-    context,
-  }, current.state);
-  const node = symbolNode(runtime.db, symbolId);
+  const symbolId = row.callee_symbol_id
+    ? Number(row.callee_symbol_id) : undefined;
+  const node = symbolId === undefined
+    ? undefined : symbolNode(runtime.db, symbolId);
   if (node) runtime.nodes.set(String(node.id), node);
   const evidence = localCallEvidence(row, node);
   const unresolvedReason = localCallUnresolvedReason(row);
@@ -247,6 +235,12 @@ function processLocalCall(
   const target = recordLocalCallObservation(runtime.recorder, edge, {
     symbolCall: row, evidence, unresolvedReason,
   });
+  if (symbolId === undefined || row.status !== 'resolved' || !node) return;
+  const { repoId, files, symbols, context, scheduling } =
+    planLocalCallExpansion(
+      runtime.db, runtime.scheduler, runtime.workspaceId, current.state,
+      row, bindings, symbolId,
+    );
   if (scheduling.kind === 'cycle')
     recordLocalCycle(runtime, current, row, target, scheduling.state,
       repoId, files, symbols);
@@ -291,7 +285,8 @@ function localTraceEdge(
     type: 'local_symbol_call',
     from: String(row.callee_expression),
     to: node?.label
-      ? String(node.label) : `symbol:${String(row.callee_symbol_id)}`,
+      ? String(node.label)
+      : `${String(row.status)}:${String(row.callee_expression)}`,
     evidence,
     confidence: Number(row.confidence ?? 0.8),
     unresolvedReason,
@@ -390,11 +385,12 @@ function recordEffectiveOutbound(
 ): EffectiveOutbound {
   const persisted = parseTraceEvidence(row.evidence_json);
   const raw = baseTraceEvidence(row, call, persisted, contextual.evidence);
-  const effective = runtimeResolution(runtime.db, row, raw, {
-    vars: runtime.options.vars,
-    dynamicMode: runtime.options.dynamicMode ?? 'strict',
-    maxDynamicCandidates: runtime.options.maxDynamicCandidates,
-  }, call.workspaceId, contextual.state);
+  const effective = runtimeEventResolution(row, raw, runtime.options.vars)
+    ?? runtimeResolution(runtime.db, row, raw, {
+      vars: runtime.options.vars,
+      dynamicMode: runtime.options.dynamicMode ?? 'strict',
+      maxDynamicCandidates: runtime.options.maxDynamicCandidates,
+    }, call.workspaceId, contextual.state);
   const target = `${effective.row.to_kind}:${effective.row.to_id}`;
   const operation = effective.row.to_kind === 'operation'
     ? operationNode(runtime.db, effective.row.to_id) : undefined;
@@ -461,15 +457,19 @@ function processEventTransitions(
 ): void {
   if (!runtime.options.includeAsync || call.call_type !== 'async_emit'
     || effective.row.edge_type !== 'HANDLER_EMITS_EVENT'
-    || typeof call.event_name_expr !== 'string') return;
-  const plans = planEventSubscriberTransitions(runtime.db, {
-    workspaceId: runtime.workspaceId ?? call.workspaceId,
-    graphGeneration: call.graphGeneration,
-    eventName: call.event_name_expr,
-  }, runtime.scheduler, current.state, current.depth, runtime.maxDepth);
-  for (const plan of plans)
+    || effective.row.to_kind !== 'event') return;
+  const planned = runtimeEventSubscriberPlans(
+    runtime.db, {
+      workspaceId: runtime.workspaceId ?? call.workspaceId,
+      graphGeneration: call.graphGeneration,
+      eventName: effective.row.to_id,
+      vars: runtime.options.vars ?? {},
+    }, runtime.scheduler, current.state, current.depth, runtime.maxDepth,
+  );
+  if (planned.diagnostic) runtime.diagnostics.push(planned.diagnostic);
+  for (const plan of planned.plans)
     recordEventTransition(runtime, current, plan,
-      effective.semanticWorkspaceId, plans.length);
+      effective.semanticWorkspaceId, planned.plans.length);
 }
 
 function recordEventTransition(

package/src/trace/030-event-runtime-resolution.ts

@@ -0,0 +1,151 @@
+import {
+  substituteVariables,
+  type RuntimeSubstitution,
+} from '../linker/dynamic-edge-resolver.js';
+import type { Db } from '../db/connection.js';
+import {
+  eventSubscriberMissingVariables,
+  planEventSubscriberTransitions,
+  type EventSubscriberTransitionQuery,
+  type PlannedEventSubscriberTransition,
+} from './011-event-subscriber-traversal.js';
+import type {
+  TraversalScopeScheduler,
+  TraversalScopeState,
+} from './010-traversal-scope.js';
+import type { TraceGraphRow } from './evidence.js';
+
+export interface EventRuntimeResolution {
+  row: TraceGraphRow;
+  evidence: Record<string, unknown>;
+  unresolvedReason?: string;
+}
+
+export interface EventSubscriberRuntimePlan {
+  plans: PlannedEventSubscriberTransition[];
+  diagnostic?: Record<string, unknown>;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function eventTemplate(evidence: Record<string, unknown>): string | undefined {
+  const resolution = record(evidence.eventTemplateResolution);
+  return typeof resolution?.original === 'string'
+    ? resolution.original : undefined;
+}
+
+function missingReason(substitution: RuntimeSubstitution): string {
+  return `Dynamic target requires runtime variable overrides: ${
+    substitution.missing.join(', ')}`;
+}
+
+function missingSubscriberDiagnostic(
+  missing: readonly string[],
+): Record<string, unknown> | undefined {
+  if (missing.length === 0) return undefined;
+  return {
+    severity: 'warning',
+    code: 'trace_runtime_variables_missing',
+    message: `Runtime variables are required to resolve dynamic event subscribers: ${
+      missing.join(', ')}`,
+    missingVariables: missing,
+    suggestions: missing.map((key) => `--var ${key}=<value>`),
+    source: 'event_subscription',
+  };
+}
+
+export function runtimeEventSubscriberPlans(
+  db: Db,
+  query: EventSubscriberTransitionQuery,
+  scheduler: TraversalScopeScheduler,
+  parent: TraversalScopeState,
+  depth: number,
+  maxDepth: number,
+): EventSubscriberRuntimePlan {
+  const missing = eventSubscriberMissingVariables(db, query);
+  return {
+    plans: planEventSubscriberTransitions(
+      db, query, scheduler, parent, depth, maxDepth,
+    ),
+    diagnostic: missingSubscriberDiagnostic(missing),
+  };
+}
+
+function eventEvidence(
+  evidence: Record<string, unknown>,
+  substitution: RuntimeSubstitution,
+  row: TraceGraphRow,
+  unresolvedReason?: string,
+): Record<string, unknown> {
+  const effectiveResolution = {
+    status: unresolvedReason ? 'dynamic' : 'terminal',
+    targetKind: row.to_kind,
+    targetId: row.to_id,
+    confidence: row.confidence,
+    unresolvedReason,
+    edgeType: row.edge_type,
+  };
+  return {
+    ...evidence,
+    runtimeSubstitutions: { eventName: substitution },
+    suppliedRuntimeVariables: Object.fromEntries(
+      substitution.supplied.map((key) => [key, true]),
+    ),
+    ...(substitution.supplied.length > 0
+      ? { runtimeVariablesApplied: true } : {}),
+    ...(substitution.missing.length > 0
+      ? { missingRuntimeVariables: substitution.missing } : {}),
+    effectiveResolution,
+    linker: {
+      status: effectiveResolution.status,
+      confidence: row.confidence,
+      reason: unresolvedReason,
+      edgeType: row.edge_type,
+    },
+  };
+}
+
+function runtimeEventRow(
+  row: TraceGraphRow,
+  evidence: Record<string, unknown>,
+  substitution: RuntimeSubstitution,
+  template: string,
+): TraceGraphRow {
+  const missing = substitution.missing.length > 0;
+  const eventName = substitution.effective ?? template;
+  const callType = evidence.callType;
+  const edgeType = callType === 'async_emit'
+    ? 'HANDLER_EMITS_EVENT' : 'EVENT_CONSUMED_BY_HANDLER';
+  return {
+    ...row,
+    edge_type: missing ? 'DYNAMIC_EDGE_CANDIDATE' : edgeType,
+    status: missing ? 'dynamic' : 'terminal',
+    to_kind: missing ? 'event_candidate' : 'event',
+    to_id: missing ? `Event: ${eventName}` : eventName,
+    unresolved_reason: missing ? missingReason(substitution) : undefined,
+  };
+}
+
+export function runtimeEventResolution(
+  row: TraceGraphRow,
+  evidence: Record<string, unknown>,
+  variables: Record<string, string> | undefined,
+): EventRuntimeResolution | undefined {
+  const template = eventTemplate(evidence);
+  if (!template || row.to_kind === 'event' && variables === undefined)
+    return undefined;
+  const substitution = substituteVariables(template, variables ?? {});
+  const effectiveRow = runtimeEventRow(
+    row, evidence, substitution, template,
+  );
+  return {
+    row: effectiveRow,
+    evidence: eventEvidence(
+      evidence, substitution, effectiveRow, effectiveRow.unresolved_reason,
+    ),
+    unresolvedReason: effectiveRow.unresolved_reason,
+  };
+}

package/src/trace/031-local-call-expansion.ts

@@ -0,0 +1,37 @@
+import type { Db } from '../db/connection.js';
+import {
+  type ContextBinding,
+} from './008-contextual-runtime-state.js';
+import {
+  type TraversalScheduleDecision,
+  type TraversalScopeScheduler,
+  type TraversalScopeState,
+} from './010-traversal-scope.js';
+import { contextForSymbolCall } from './017-trace-context.js';
+
+export interface LocalCallExpansion {
+  repoId: number;
+  files: Set<string>;
+  symbols: Set<number>;
+  context: Map<string, ContextBinding>;
+  scheduling: TraversalScheduleDecision;
+}
+
+export function planLocalCallExpansion(
+  db: Db,
+  scheduler: TraversalScopeScheduler,
+  workspaceId: number | undefined,
+  parent: TraversalScopeState,
+  row: Record<string, unknown>,
+  bindings: Map<string, ContextBinding>,
+  symbolId: number,
+): LocalCallExpansion {
+  const symbols = new Set([symbolId]);
+  const files = new Set([String(row.calleeFile)]);
+  const repoId = Number(row.calleeRepoId);
+  const context = contextForSymbolCall(db, row, bindings);
+  const scheduling = scheduler.schedule({
+    workspaceId, repoId, files, symbolIds: symbols, context,
+  }, parent);
+  return { repoId, files, symbols, context, scheduling };
+}

package/src/trace/implementation-hints.ts

@@ -1,5 +1,6 @@
 import type { ImplementationHint } from '../types.js';
 import { projectBounded } from '../utils/000-bounded-projection.js';
+import { compareBinary } from './010-traversal-scope.js';
 
 interface Candidate {
   accepted?: boolean;
@@ -106,6 +107,7 @@ export function implementationHintSuggestions(rawEvidence: Record<string, unknow
 
 export function implementationHintSuggestionProjection(
   rawEvidence: Record<string, unknown>,
+  limit?: number,
 ): ImplementationHintSuggestionProjection {
   const evidence = asEvidence(rawEvidence);
   const accepted = (evidence.candidates ?? []).filter((candidate) => candidate.accepted);
@@ -119,7 +121,7 @@ export function implementationHintSuggestionProjection(
   }
   const repos = selectableRepositories(accepted);
   const repositoryProjection = projectBounded(
-    repos, (left, right) => left.localeCompare(right),
+    repos, compareBinary, limit,
   );
   const suggestions = accepted
     .flatMap((candidate) => {
@@ -142,7 +144,7 @@ export function implementationHintSuggestionProjection(
         cli: `--implementation-hint ${hintString(hint)}`,
       }];
     });
-  const projection = projectBounded(suggestions, compareSuggestion);
+  const projection = projectBounded(suggestions, compareSuggestion, limit);
   return {
     suggestions: projection.items,
     suggestionCount: projection.totalCount,
@@ -170,15 +172,16 @@ function projectedSuggestions(value: unknown): ImplementationHintSuggestionProje
 }
 
 function compareHints(left: ImplementationHint, right: ImplementationHint): number {
-  return hintString(left).localeCompare(hintString(right));
+  return compareBinary(hintString(left), hintString(right));
 }
 
 function compareSuggestion(
   left: Record<string, unknown>,
   right: Record<string, unknown>,
 ): number {
-  return String(left.cli ?? '').localeCompare(String(right.cli ?? ''))
-    || String(left.implementationRepo ?? '').localeCompare(
+  return compareBinary(String(left.cli ?? ''), String(right.cli ?? ''))
+    || compareBinary(
+      String(left.implementationRepo ?? ''),
       String(right.implementationRepo ?? ''),
     );
 }
@@ -202,7 +205,7 @@ function selectableRepositories(candidates: Candidate[]): string[] {
   const repos = new Set(candidates.flatMap((candidate) => candidate.handlerPackage?.name ? [candidate.handlerPackage.name] : []));
   return [...repos]
     .filter((repo) => candidates.filter((candidate) => candidateMatchesRepo(candidate, repo)).length === 1)
-    .sort();
+    .sort(compareBinary);
 }
 
 function assignHintField(hint: Partial<ImplementationHint>, key: string, value: string): void {

package/src/trace/selectors.ts

@@ -550,6 +550,7 @@ export function ambiguousStartDiagnostic(
     severity: 'warning',
     code: 'trace_start_ambiguous',
     message,
+    selectorKind: 'operation',
     normalizedSelectorValue: requested,
     resolutionStage: 'operation',
     resolutionStatus: 'ambiguous_operation',

package/src/types.ts

@@ -203,7 +203,8 @@ export interface ServiceBindingReference {
   bindingSiteEndOffset?: number;
   resolutionStrategy?: 'lexical_declaration'
     | 'lexical_alias_declaration'
-    | 'deterministic_reaching_assignment';
+    | 'deterministic_reaching_assignment'
+    | 'single_hop_helper_return';
   lexicalScopeChain?: LexicalScopeFact[];
   bindingScopeIndex?: number;
   scopeChainTotal: number;

package/src/version.ts

@@ -1,4 +1,4 @@
 import packageJson from '../package.json' with { type: 'json' };
 
 export const VERSION = packageJson.version;
-export const ANALYZER_VERSION = '0.1.68-facts.1';
+export const ANALYZER_VERSION = '0.1.69-facts.1';