@saptools/service-flow 0.1.67 → 0.1.68

package/src/trace/028-trace-operation-execution.ts

@@ -0,0 +1,336 @@
+import type { Db } from '../db/connection.js';
+import type { TraceEdge } from '../types.js';
+import { implementationHintDiagnostic } from './implementation-hints.js';
+import { contextualImplementationSelection } from './005-implementation-selection.js';
+import type { ContextBinding } from './008-contextual-runtime-state.js';
+import {
+  handlerMethodNode,
+  withSelectedHandlerProvenance,
+  type SelectedHandlerEvidence,
+} from './009-selected-handler-provenance.js';
+import type { TraversalScopeState } from './010-traversal-scope.js';
+import type { TraceGraphEdgeRow } from './012-trace-graph-lookups.js';
+import {
+  enqueueCausalScope,
+  type TraceQueueScope,
+} from './013-trace-root-scopes.js';
+import { parseTraceEvidence } from './017-trace-context.js';
+import {
+  recordCycleObservation,
+  recordImplementationObservation,
+} from './019-trace-edge-semantics.js';
+import {
+  handlerFilesForOperation,
+  handlerScope,
+  implementationScope,
+} from './025-trace-implementation-scope.js';
+import type {
+  CallRow,
+  EffectiveOutbound,
+  TraceExecutionRuntime,
+} from './027-trace-scope-execution.js';
+
+interface OperationSelection {
+  implementation: ReturnType<typeof implementationScope>;
+  contextMethodId?: string;
+  selectedHandlerAvailable: boolean;
+}
+
+export function processOperationTarget(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  call: CallRow,
+  effective: EffectiveOutbound,
+): void {
+  const selection = selectOperation(runtime, current, effective);
+  if (current.depth >= runtime.maxDepth) return;
+  scheduleOperation(runtime, current, call, effective, selection);
+}
+
+function selectOperation(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  effective: EffectiveOutbound,
+): OperationSelection {
+  const implementation = implementationScope(
+    runtime.db, effective.row.to_id,
+  );
+  const context = contextualImplementationSelection(
+    runtime.db, implementation.edge, effective.row.to_id,
+    current.repoId, effective.evidence, runtime.hintOptions,
+  );
+  const available = implementation.edge
+    ? recordOperationImplementation(runtime, current, effective,
+      implementation.edge, context)
+    : true;
+  return {
+    implementation,
+    contextMethodId: context.methodId,
+    selectedHandlerAvailable: available,
+  };
+}
+
+function recordOperationImplementation(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  effective: EffectiveOutbound,
+  edge: TraceGraphEdgeRow,
+  context: ReturnType<typeof contextualImplementationSelection>,
+): boolean {
+  const evidence = parseTraceEvidence(edge.evidence_json);
+  const hintDiagnostic = implementationHintDiagnostic(context, evidence);
+  if (hintDiagnostic) runtime.diagnostics.unshift(hintDiagnostic);
+  const methodId = edge.status === 'resolved' ? edge.to_id : context.methodId;
+  const selectionEvidence = contextualSelectionEvidence(evidence, context);
+  const selected = methodId
+    ? withSelectedHandlerProvenance(
+      selectionEvidence, methodId, handlerMethodNode(runtime.db, methodId),
+    )
+    : { evidence: selectionEvidence };
+  recordSelectedOperation(
+    runtime, current, effective, edge, context, methodId, selected,
+  );
+  return !selected.unresolvedReason;
+}
+
+function recordSelectedOperation(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  effective: EffectiveOutbound,
+  edge: TraceGraphEdgeRow,
+  context: ReturnType<typeof contextualImplementationSelection>,
+  methodId: string | undefined,
+  selected: SelectedHandlerEvidence,
+): void {
+  retainSelectedHandler(runtime, selected);
+  const unresolvedReason = operationUnresolvedReason(edge, context, selected);
+  const traceEdge = implementationTraceEdge(
+    current.depth, effective.to, edge, selected, unresolvedReason,
+  );
+  const scope = methodId ? handlerScope(runtime.db, methodId) : undefined;
+  recordImplementationObservation(runtime.recorder, traceEdge, {
+    operationId: effective.row.to_id,
+    handlerMethodId: methodId,
+    handlerSymbolId: scope?.symbolId,
+    graphEdgeId: edge.id,
+    persistedStatus: edge.status,
+    persistedTargetKind: edge.to_kind,
+    persistedTargetId: edge.to_id,
+    effectiveStatus: context.methodId ? 'resolved' : String(edge.status),
+    strategy: implementationStrategy(context),
+    guided: context.evidence.guided === true,
+    contextual: contextualSelection(context),
+    unresolvedReason,
+    evidence: selected.evidence,
+    site: effective.evidence,
+  });
+}
+
+function retainSelectedHandler(
+  runtime: TraceExecutionRuntime,
+  selected: SelectedHandlerEvidence,
+): void {
+  if (selected.diagnostic) runtime.diagnostics.unshift(selected.diagnostic);
+  if (selected.handler)
+    runtime.nodes.set(String(selected.handler.id), selected.handler);
+}
+
+function operationUnresolvedReason(
+  edge: TraceGraphEdgeRow,
+  context: ReturnType<typeof contextualImplementationSelection>,
+  selected: SelectedHandlerEvidence,
+): string | undefined {
+  if (selected.unresolvedReason) return selected.unresolvedReason;
+  if (edge.status === 'resolved' || context.methodId) return undefined;
+  return String(edge.unresolved_reason ?? edge.status);
+}
+
+function contextualSelection(
+  context: ReturnType<typeof contextualImplementationSelection>,
+): boolean {
+  return Boolean(context.methodId)
+    && context.evidence.strategy !== 'implementation_repo_hint';
+}
+
+function implementationStrategy(
+  context: ReturnType<typeof contextualImplementationSelection>,
+): string {
+  return String(context.evidence.strategy
+    ?? (context.methodId
+      ? 'contextual_implementation_selection' : 'indexed_operation_graph'));
+}
+
+function contextualSelectionEvidence(
+  evidence: Record<string, unknown>,
+  context: ReturnType<typeof contextualImplementationSelection>,
+): Record<string, unknown> {
+  return context.methodId ? {
+    ...evidence,
+    contextualImplementationSelected:
+      context.evidence.strategy !== 'implementation_repo_hint',
+    contextualImplementation: context.evidence,
+    implementationSelection: context.evidence,
+  } : {
+    ...evidence,
+    contextualImplementation: context.evidence,
+    implementationSelection: context.evidence,
+  };
+}
+
+function implementationTraceEdge(
+  depth: number,
+  from: string,
+  edge: TraceGraphEdgeRow,
+  selected: SelectedHandlerEvidence,
+  unresolvedReason: string | undefined,
+): TraceEdge {
+  return {
+    step: depth,
+    type: 'operation_implemented_by_handler',
+    from,
+    to: selected.handler?.label
+      ? String(selected.handler.label) : `${edge.to_kind}:${edge.to_id}`,
+    evidence: selected.evidence,
+    confidence: Number(edge.confidence ?? 0),
+    unresolvedReason,
+  };
+}
+
+function scheduleOperation(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  call: CallRow,
+  effective: EffectiveOutbound,
+  selection: OperationSelection,
+): void {
+  const contextScope = operationContextScope(runtime.db, selection);
+  const files = operationFiles(runtime.db, effective, selection, contextScope);
+  const symbols = operationSymbols(selection, contextScope);
+  if (!operationCanSchedule(selection, contextScope, files)) return;
+  scheduleOperationScope(
+    runtime, current, call, effective, selection, contextScope, files, symbols,
+  );
+}
+
+function operationContextScope(
+  db: Db,
+  selection: OperationSelection,
+): ReturnType<typeof handlerScope> {
+  return selection.contextMethodId
+    ? handlerScope(db, selection.contextMethodId) : undefined;
+}
+
+function operationFiles(
+  db: Db,
+  effective: EffectiveOutbound,
+  selection: OperationSelection,
+  contextScope: ReturnType<typeof handlerScope>,
+): Set<string> {
+  if (contextScope) return contextScope.files;
+  if (selection.implementation.files.size > 0)
+    return selection.implementation.files;
+  return handlerFilesForOperation(db, effective.row.to_id);
+}
+
+function operationSymbols(
+  selection: OperationSelection,
+  contextScope: ReturnType<typeof handlerScope>,
+): Set<number> | undefined {
+  if (contextScope?.symbolId) return new Set([contextScope.symbolId]);
+  const symbolId = selection.implementation.symbolId;
+  return symbolId ? new Set([symbolId]) : undefined;
+}
+
+function operationCanSchedule(
+  selection: OperationSelection,
+  contextScope: ReturnType<typeof handlerScope>,
+  files: ReadonlySet<string>,
+): boolean {
+  if (!selection.selectedHandlerAvailable || files.size === 0) return false;
+  const edge = selection.implementation.edge;
+  if (!edge) return false;
+  return edge.status === 'resolved' || contextScope !== undefined;
+}
+
+function scheduleOperationScope(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  call: CallRow,
+  effective: EffectiveOutbound,
+  selection: OperationSelection,
+  contextScope: ReturnType<typeof handlerScope>,
+  files: Set<string>,
+  symbols: Set<number> | undefined,
+): void {
+  const repoId = contextScope?.repoId ?? selection.implementation.repoId
+    ?? operationRepositoryId(runtime.db, effective.row.to_id);
+  const context = new Map<string, ContextBinding>();
+  const scheduling = runtime.scheduler.schedule({
+    workspaceId: runtime.workspaceId ?? call.workspaceId,
+    repoId,
+    files,
+    symbolIds: symbols,
+    context,
+  }, current.state);
+  if (scheduling.kind === 'cycle')
+    recordOperationCycle(
+      runtime, current, call, effective, scheduling.state,
+      repoId, files, symbols,
+    );
+  if (scheduling.kind === 'scheduled')
+    enqueueCausalScope(runtime.queue, runtime.pendingRoots, {
+      repoId,
+      files,
+      symbolIds: symbols,
+      depth: current.depth + 1,
+      context,
+      state: scheduling.state,
+    });
+}
+
+function operationRepositoryId(
+  db: Db,
+  operationId: string,
+): number | undefined {
+  return db.prepare(`SELECT s.repo_id repoId
+    FROM cds_operations o JOIN cds_services s ON s.id=o.service_id
+    WHERE o.id=?`).get(operationId)?.repoId as number | undefined;
+}
+
+function recordOperationCycle(
+  runtime: TraceExecutionRuntime,
+  current: TraceQueueScope,
+  call: CallRow,
+  effective: EffectiveOutbound,
+  state: TraversalScopeState,
+  repoId: number | undefined,
+  files: Set<string>,
+  symbols: Set<number> | undefined,
+): void {
+  const evidence = {
+    ...effective.evidence,
+    cycle: true,
+    cycleReason: 'structural_ancestry_cycle',
+  };
+  const edge: TraceEdge = {
+    step: current.depth,
+    type: 'cycle',
+    from: effective.to,
+    to: state.structuralKey,
+    evidence,
+    confidence: 1,
+    unresolvedReason:
+      'Cycle detected in structural ancestry; downstream scope was not expanded',
+  };
+  recordCycleObservation(runtime.recorder, edge, effective.semantic.target, {
+    workspaceId: effective.semanticWorkspaceId,
+    repositoryId: repoId,
+    sourceFiles: files,
+    symbolIds: symbols,
+    structuralKey: state.structuralKey,
+  }, {
+    graphEdgeId: effective.evidence.persistedGraphEdgeId,
+    outboundCallId: call.id,
+    operationId: effective.row.to_id,
+  }, call);
+}

package/src/trace/029-trace-start-implementation.ts

@@ -0,0 +1,172 @@
+import type { Db } from '../db/connection.js';
+import type { TraceEdge } from '../types.js';
+import { hintedImplementationSelection } from './005-implementation-selection.js';
+import {
+  handlerMethodNode,
+  withSelectedHandlerProvenance,
+  type SelectedHandlerEvidence,
+} from './009-selected-handler-provenance.js';
+import {
+  operationNode,
+  type TraceGraphEdgeRow,
+} from './012-trace-graph-lookups.js';
+import { parseTraceEvidence } from './017-trace-context.js';
+import { recordImplementationObservation } from './019-trace-edge-semantics.js';
+import {
+  handlerScope,
+  implementationScope,
+} from './025-trace-implementation-scope.js';
+import type { TraceExecutionRuntime } from './027-trace-scope-execution.js';
+
+interface StartImplementationSelection {
+  edge: TraceGraphEdgeRow;
+  operationNode?: Record<string, unknown>;
+  selectedMethodId?: string;
+  selected: SelectedHandlerEvidence;
+  selectedSymbolId?: number;
+  effectiveStatus: string;
+  strategy: string;
+  guided: boolean;
+  unresolvedReason?: string;
+}
+
+function selectedStartImplementation(
+  runtime: TraceExecutionRuntime,
+  operationId: string,
+): StartImplementationSelection | undefined {
+  const operation = operationNode(runtime.db, operationId);
+  if (operation) runtime.nodes.set(String(operation.id), operation);
+  const implementation = implementationScope(runtime.db, operationId);
+  const startSelection = hintedImplementationSelection(
+    runtime.db, implementation.edge, operationId, runtime.hintOptions,
+  );
+  const edge = implementation.edge;
+  if (!edge) return undefined;
+  const selectedMethodId = startSelectedMethod(edge, startSelection.methodId);
+  if (!selectedMethodId && edge.status !== 'resolved') return undefined;
+  const evidence = startImplementationEvidence(
+    edge, operationId, selectedMethodId, startSelection,
+  );
+  const selected = startSelectedHandler(
+    runtime.db, evidence, selectedMethodId,
+  );
+  const scope = selectedMethodId
+    ? handlerScope(runtime.db, selectedMethodId) : undefined;
+  return {
+    edge, operationNode: operation, selectedMethodId, selected,
+    selectedSymbolId: scope?.symbolId,
+    effectiveStatus: startEffectiveStatus(edge, startSelection.methodId),
+    strategy: startStrategy(startSelection.evidence.strategy),
+    guided: startSelection.evidence.guided === true,
+    unresolvedReason: startUnresolvedReason(
+      edge, selected, startSelection.methodId,
+    ),
+  };
+}
+
+function startSelectedMethod(
+  edge: TraceGraphEdgeRow,
+  hintedMethodId: string | undefined,
+): string | undefined {
+  return edge.status === 'resolved' ? edge.to_id : hintedMethodId;
+}
+
+function startSelectedHandler(
+  db: Db,
+  evidence: Record<string, unknown>,
+  methodId: string | undefined,
+): SelectedHandlerEvidence {
+  if (!methodId) return { evidence };
+  return withSelectedHandlerProvenance(
+    evidence, methodId, handlerMethodNode(db, methodId),
+  );
+}
+
+function startEffectiveStatus(
+  edge: TraceGraphEdgeRow,
+  hintedMethodId: string | undefined,
+): string {
+  return hintedMethodId ? 'resolved' : String(edge.status ?? 'unresolved');
+}
+
+function startStrategy(value: unknown): string {
+  return typeof value === 'string' ? value : 'indexed_operation_graph';
+}
+
+function startUnresolvedReason(
+  edge: TraceGraphEdgeRow,
+  selected: SelectedHandlerEvidence,
+  hintedMethodId: string | undefined,
+): string | undefined {
+  if (selected.unresolvedReason) return selected.unresolvedReason;
+  if (edge.status === 'resolved' || hintedMethodId) return undefined;
+  return String(edge.unresolved_reason ?? edge.status);
+}
+
+function startImplementationEvidence(
+  edge: TraceGraphEdgeRow,
+  operationId: string,
+  selectedMethodId: string | undefined,
+  selection: ReturnType<typeof hintedImplementationSelection>,
+): Record<string, unknown> {
+  return {
+    ...parseTraceEvidence(edge.evidence_json),
+    startResolution: {
+      strategy: 'indexed_operation_graph',
+      matchedOperationId: operationId,
+      implementationEdgeId: edge.id,
+      implementationStatus: edge.status,
+      selectedHandlerMethodId: selectedMethodId,
+    },
+    implementationSelection: selection.methodId
+      ? selection.evidence : undefined,
+  };
+}
+
+export function recordTraceStartImplementation(
+  runtime: TraceExecutionRuntime,
+  operationId: string,
+): void {
+  const selection = selectedStartImplementation(runtime, operationId);
+  if (!selection) return;
+  const selected = selection.selected;
+  if (selected.diagnostic)
+    runtime.diagnostics.unshift(selected.diagnostic);
+  if (selected.handler)
+    runtime.nodes.set(String(selected.handler.id), selected.handler);
+  const edge = startImplementationTraceEdge(operationId, selection);
+  recordImplementationObservation(runtime.recorder, edge, {
+    operationId,
+    handlerMethodId: selection.selectedMethodId,
+    handlerSymbolId: selection.selectedSymbolId,
+    graphEdgeId: selection.edge.id,
+    persistedStatus: selection.edge.status,
+    persistedTargetKind: selection.edge.to_kind,
+    persistedTargetId: selection.edge.to_id,
+    effectiveStatus: selection.effectiveStatus,
+    strategy: selection.strategy,
+    guided: selection.guided,
+    unresolvedReason: selection.unresolvedReason,
+    evidence: selected.evidence,
+    site: selection.operationNode ?? {},
+  });
+}
+
+function startImplementationTraceEdge(
+  operationId: string,
+  selection: StartImplementationSelection,
+): TraceEdge {
+  const selected = selection.selected;
+  return {
+    step: 1,
+    type: 'operation_implemented_by_handler',
+    from: selection.operationNode?.label
+      ? String(selection.operationNode.label) : `operation:${operationId}`,
+    to: selected.handler?.label
+      ? String(selected.handler.label)
+      : `${selection.edge.to_kind}:${selection.edge.to_id}`,
+    evidence: selected.evidence,
+    confidence: Number(selection.edge.confidence ?? 0),
+    unresolvedReason: selection.unresolvedReason,
+  };
+}