@principal-ai/subsystems-core 0.29.0

package/src/workflow/example.ts

@@ -0,0 +1,330 @@
+/**
+ * Example: Using the Workflow Template System
+ *
+ * This example demonstrates how to use the workflow renderer
+ * to transform OTEL events into human-readable workflows.
+ */
+
+import { renderWorkflow } from './template-renderer';
+import type { WorkflowTemplate, OtelEvent } from './types';
+
+// Example 1: Simple Success Scenario
+function exampleSuccess() {
+  const template: WorkflowTemplate = {
+    version: '1.0.0',
+    canvas: 'example.otel.canvas',
+    name: 'Example Execution',
+    description: 'Simple execution workflow',
+    spanPattern: 'example.execution',
+    scenarioSelection: 'first-match',
+    showLogsPerSpan: true,
+    scenarios: [
+      {
+        id: 'success',
+        priority: 1,
+        description: 'Successful execution',
+        template: {
+          introduction: '✅ Execution Successful\n{"━".repeat(50)}',
+          span: '→ {span.name}',
+          children: 'recurse',
+          events: {
+            'execution.started': '  🔄 Starting execution',
+            'execution.complete': '  ✅ Completed in {duration.ms}ms with {result.count} items',
+          },
+          logs: {
+            info: '    ℹ️  {log.body}',
+            debug: '    🔍 {log.body}',
+          },
+          summary: '{"━".repeat(50)}\n\n✅ SUCCESS\n\nProcessed {result.count} items in {duration.ms}ms',
+        },
+      },
+    ],
+  };
+
+  const events: OtelEvent[] = [
+    {
+      name: 'execution.started',
+      timestamp: 1000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+    },
+    {
+      name: 'log.info',
+      timestamp: 1100,
+      type: 'log',
+      spanId: 'span1',
+      traceId: 'trace1',
+      severityText: 'INFO',
+      severityNumber: 9,
+      body: 'Processing items...',
+    },
+    {
+      name: 'execution.complete',
+      timestamp: 2000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+      attributes: {
+        'result.status': 'success',
+        'result.count': 42,
+        'duration.ms': 1000,
+      },
+    },
+  ];
+
+  const result = renderWorkflow(template, events);
+  console.log('=== Example 1: Success Scenario ===\n');
+  console.log(result.text);
+  console.log('\nMetadata:', result.metadata);
+  console.log('\n');
+}
+
+// Example 2: Multi-scenario with Violations
+function exampleWithViolations() {
+  const template: WorkflowTemplate = {
+    version: '1.0.0',
+    canvas: 'validation.otel.canvas',
+    name: 'Validation Execution',
+    description: 'Validation with multiple scenarios',
+    spanPattern: 'validation.run',
+    scenarioSelection: 'first-match',
+    scenarios: [
+      {
+        id: 'errors',
+        priority: 1,
+        description: 'Has error-level violations',
+        template: {
+          introduction: '❌ Validation Failed\n{"━".repeat(50)}',
+          span: '→ {span.name}',
+          children: 'recurse',
+          events: {
+            'validation.started': '  🔍 Validating configuration',
+            'validation.complete':
+              '  ❌ Found {result.errors} errors and {result.warnings} warnings',
+          },
+          summary:
+            '{"━".repeat(50)}\n\n❌ FAILED\n\nErrors: {result.errors}\nWarnings: {result.warnings}',
+        },
+      },
+      {
+        id: 'warnings',
+        priority: 2,
+        description: 'Has warnings only',
+        template: {
+          introduction: '⚠️  Validation Passed with Warnings\n{"━".repeat(50)}',
+          span: '→ {span.name}',
+          children: 'recurse',
+          events: {
+            'validation.started': '  🔍 Validating configuration',
+            'validation.complete': '  ⚠️  Found {result.warnings} warnings',
+          },
+          summary: '{"━".repeat(50)}\n\n⚠️  PASSED WITH WARNINGS\n\nWarnings: {result.warnings}',
+        },
+      },
+      {
+        id: 'success',
+        priority: 3,
+        description: 'All checks passed',
+        template: {
+          introduction: '✅ Validation Passed\n{"━".repeat(50)}',
+          span: '→ {span.name}',
+          children: 'recurse',
+          events: {
+            'validation.started': '  🔍 Validating configuration',
+            'validation.complete': '  ✅ All checks passed',
+          },
+          summary: '{"━".repeat(50)}\n\n✅ SUCCESS\n\nNo violations found.',
+        },
+      },
+    ],
+  };
+
+  // Scenario 1: Errors
+  const eventsWithErrors: OtelEvent[] = [
+    {
+      name: 'validation.started',
+      timestamp: 1000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+    },
+    {
+      name: 'validation.complete',
+      timestamp: 2000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+      attributes: {
+        'result.errors': 3,
+        'result.warnings': 2,
+      },
+    },
+  ];
+
+  console.log('=== Example 2a: Validation with Errors ===\n');
+  const result1 = renderWorkflow(template, eventsWithErrors);
+  console.log(result1.text);
+  console.log('\nSelected scenario:', result1.scenarioId);
+  console.log('\n');
+
+  // Scenario 2: Warnings only
+  const eventsWithWarnings: OtelEvent[] = [
+    {
+      name: 'validation.started',
+      timestamp: 1000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+    },
+    {
+      name: 'validation.complete',
+      timestamp: 2000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+      attributes: {
+        'result.errors': 0,
+        'result.warnings': 5,
+      },
+    },
+  ];
+
+  console.log('=== Example 2b: Validation with Warnings ===\n');
+  const result2 = renderWorkflow(template, eventsWithWarnings);
+  console.log(result2.text);
+  console.log('\nSelected scenario:', result2.scenarioId);
+  console.log('\n');
+
+  // Scenario 3: Success
+  const eventsSuccess: OtelEvent[] = [
+    {
+      name: 'validation.started',
+      timestamp: 1000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+    },
+    {
+      name: 'validation.complete',
+      timestamp: 2000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+      attributes: {
+        'result.errors': 0,
+        'result.warnings': 0,
+      },
+    },
+  ];
+
+  console.log('=== Example 2c: Validation Success ===\n');
+  const result3 = renderWorkflow(template, eventsSuccess);
+  console.log(result3.text);
+  console.log('\nSelected scenario:', result3.scenarioId);
+  console.log('\n');
+}
+
+// Example 3: Span Tree with Hierarchy
+function exampleSpanTree() {
+  const template: WorkflowTemplate = {
+    version: '1.0.0',
+    canvas: 'hierarchy.otel.canvas',
+    name: 'Hierarchical Execution',
+    description: 'Demonstrates span tree rendering',
+    spanPattern: 'root.operation',
+    scenarioSelection: 'first-match',
+    showLogsPerSpan: true,
+    scenarios: [
+      {
+        id: 'default',
+        priority: 1,
+        description: 'Default',
+        template: {
+          introduction: '📋 Execution Trace\n{"━".repeat(50)}',
+          span: '→ {span.name}',
+          children: 'recurse',
+          events: {
+            'root.operation': '  🔄 Operation started',
+          },
+          logs: {
+            info: '  ℹ️  {log.body}',
+            error: '  ❌ {log.body}',
+          },
+          summary: '{"━".repeat(50)}\nComplete',
+        },
+      },
+    ],
+  };
+
+  const events: OtelEvent[] = [
+    {
+      name: 'root.operation',
+      timestamp: 1000,
+      type: 'span',
+      spanId: 'span1',
+      traceId: 'trace1',
+    },
+    {
+      name: 'log.info',
+      timestamp: 1100,
+      type: 'log',
+      spanId: 'span1',
+      traceId: 'trace1',
+      severityText: 'INFO',
+      severityNumber: 9,
+      body: 'Root operation started',
+    },
+    {
+      name: 'child.operation',
+      timestamp: 1200,
+      type: 'span',
+      spanId: 'span2',
+      parentSpanId: 'span1',
+      traceId: 'trace1',
+    },
+    {
+      name: 'log.info',
+      timestamp: 1300,
+      type: 'log',
+      spanId: 'span2',
+      traceId: 'trace1',
+      severityText: 'INFO',
+      severityNumber: 9,
+      body: 'Processing child task',
+    },
+    {
+      name: 'grandchild.operation',
+      timestamp: 1400,
+      type: 'span',
+      spanId: 'span3',
+      parentSpanId: 'span2',
+      traceId: 'trace1',
+    },
+    {
+      name: 'log.info',
+      timestamp: 1500,
+      type: 'log',
+      spanId: 'span3',
+      traceId: 'trace1',
+      severityText: 'INFO',
+      severityNumber: 9,
+      body: 'Executing grandchild task',
+    },
+  ];
+
+  console.log('=== Example 3: Span Tree Hierarchy ===\n');
+  const result = renderWorkflow(template, events);
+  console.log(result.text);
+  console.log('\n');
+}
+
+// Run all examples
+// Commented out for CommonJS compatibility - uncomment if using ESM
+// if (import.meta.main) {
+//   exampleSuccess();
+//   exampleWithViolations();
+//   exampleSpanTree();
+// }
+
+export { exampleSuccess, exampleWithViolations, exampleSpanTree };

package/src/workflow/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Workflow Template System
+ *
+ * Transform OpenTelemetry event streams into human-readable execution workflows.
+ *
+ * @module workflow
+ */
+
+// Types
+export type {
+  WorkflowTemplate,
+  WorkflowScenario,
+  ScenarioOutcomeType,
+  ScenarioTemplate,
+  EventTemplate,
+  LogTemplates,
+  FormattingOptions,
+  OtelEvent,
+  OtelSignal,
+  WorkflowContext,
+  WorkflowResult,
+  ScenarioMatchResult,
+  ScenarioMatchDetail,
+  EnhancedScenarioMatchResult,
+  WorkflowMatch,
+  SpanTreeNode,
+} from './types';
+
+// Type helpers
+export {
+  isEventTemplate,
+  getEventTemplateString,
+  getEventSpan,
+  getWorkflowRootSpan,
+} from './types';
+
+// Scenario Matching
+export { selectScenario, getRequiredEvents, hasEventMatching, computeAggregates, getNestedValue, setNestedValue } from './scenario-matcher';
+
+// Template Parsing
+export { parseTemplate, ParsedTemplate } from './template-parser';
+export type { TemplateSegment, TemplateContext, TemplateValue, TemplateData } from './template-parser';
+
+// Template Rendering
+export { renderWorkflow, renderEventTemplate } from './template-renderer';
+
+// Validation
+export type {
+  WorkflowValidationContext,
+  WorkflowViolation,
+  WorkflowValidationResult,
+} from './validator';
+export { WorkflowValidator, createWorkflowValidator } from './validator';
+
+// Edge Derivation
+export type {
+  DerivedEdge,
+  WorkflowEdgeDerivationResult,
+  EdgeDerivationResult,
+} from './edge-derivation';
+export {
+  extractEventSpans,
+  deriveEdgesFromSequence,
+  deriveWorkflowEdges,
+  deriveEdgesFromWorkflows,
+  groupEdgesBySources,
+} from './edge-derivation';
+
+// Edge Validation
+export type {
+  SpanNodeInfo,
+  CanvasEdgeInfo,
+  EdgeValidationResult,
+  ValidatedEdge,
+  MissingEdge,
+  UnusedEdge,
+  UnmatchedSpan,
+} from './edge-validation';
+export {
+  extractSpanNodes,
+  extractCanvasEdges,
+  matchSpanToPattern,
+  findMatchingNode,
+  validateEdges,
+  formatValidationResult,
+} from './edge-validation';

package/src/workflow/scenario-matcher.ts

@@ -0,0 +1,253 @@
+/**
+ * Scenario Matching Logic
+ *
+ * Selects the appropriate workflow scenario based on which events occurred
+ * during execution. Uses priority-based, first-match-wins algorithm.
+ */
+
+import type {
+  WorkflowScenario,
+  WorkflowTemplate,
+  OtelEvent,
+  ScenarioMatchDetail,
+  EnhancedScenarioMatchResult,
+} from './types';
+
+/**
+ * Get required events for a scenario (derived from template.events)
+ *
+ * @param scenario - Scenario to extract events from
+ * @returns Array of event names required for this scenario to match
+ */
+export function getRequiredEvents(scenario: WorkflowScenario): string[] {
+  return Object.keys(scenario.template?.events || {});
+}
+
+/**
+ * Calculate detailed match information for a scenario
+ *
+ * @param scenario - Scenario to evaluate
+ * @param events - Events from the trace
+ * @returns Detailed match information
+ */
+function calculateMatchDetails(
+  scenario: WorkflowScenario,
+  events: OtelEvent[]
+): ScenarioMatchDetail {
+  const requiredEventNames = getRequiredEvents(scenario);
+  const totalRequiredEvents = requiredEventNames.length;
+
+  // Edge case: catch-all scenario (no required events)
+  if (totalRequiredEvents === 0) {
+    return {
+      scenario,
+      matchPercentage: 0,
+      matchedEventCount: 0,
+      totalRequiredEvents: 0,
+      matchedEventNames: [],
+      missingEventNames: [],
+      isFullMatch: false,
+      isCatchAll: true,
+    };
+  }
+
+  const matchedEventNames: string[] = [];
+  const missingEventNames: string[] = [];
+
+  for (const eventName of requiredEventNames) {
+    const hasEvent = events.some((e) => e.name === eventName);
+
+    if (hasEvent) {
+      matchedEventNames.push(eventName);
+    } else {
+      missingEventNames.push(eventName);
+    }
+  }
+
+  const matchedEventCount = matchedEventNames.length;
+  const matchPercentage = (matchedEventCount / totalRequiredEvents) * 100;
+
+  return {
+    scenario,
+    matchPercentage,
+    matchedEventCount,
+    totalRequiredEvents,
+    matchedEventNames,
+    missingEventNames,
+    isFullMatch: matchPercentage === 100,
+    isCatchAll: false,
+  };
+}
+
+/**
+ * Select matching scenarios from a workflow template
+ *
+ * Returns ALL scenarios with 100% match (sorted by priority),
+ * or partial matches (sorted by % then priority) if no full matches.
+ *
+ * @param template - Workflow template with scenarios
+ * @param events - Collected OTEL events
+ * @returns Enhanced match result (never throws)
+ */
+export function selectScenario(
+  template: WorkflowTemplate,
+  events: OtelEvent[]
+): EnhancedScenarioMatchResult {
+  const fullMatches: ScenarioMatchDetail[] = [];
+  const partialMatches: ScenarioMatchDetail[] = [];
+
+  // Evaluate all scenarios
+  for (const scenario of template.scenarios) {
+    const matchDetail = calculateMatchDetails(scenario, events);
+
+    if (matchDetail.isCatchAll) {
+      // Catch-all scenarios go to partial matches
+      partialMatches.push(matchDetail);
+    } else if (matchDetail.isFullMatch) {
+      fullMatches.push(matchDetail);
+    } else {
+      partialMatches.push(matchDetail);
+    }
+  }
+
+  // Sort full matches by priority (ascending)
+  fullMatches.sort((a, b) => a.scenario.priority - b.scenario.priority);
+
+  // Sort partial matches by percentage (descending), then priority (ascending)
+  partialMatches.sort((a, b) => {
+    const percentDiff = b.matchPercentage - a.matchPercentage;
+    if (percentDiff !== 0) return percentDiff;
+    return a.scenario.priority - b.scenario.priority;
+  });
+
+  // Determine recommended scenario
+  const recommendedScenario =
+    fullMatches.length > 0 ? fullMatches[0] : partialMatches.length > 0 ? partialMatches[0] : null;
+
+  return {
+    fullMatches,
+    partialMatches,
+    recommendedScenario,
+    totalTraceEvents: events.length,
+    totalScenariosEvaluated: template.scenarios.length,
+  };
+}
+
+
+/**
+ * Check if any event matches the given event name (exact match)
+ *
+ * @param events - Events to search
+ * @param eventName - Event name to match (exact string match)
+ * @returns True if any event matches the name
+ */
+export function hasEventMatching(events: OtelEvent[], eventName: string): boolean {
+  return events.some((event) => event.name === eventName);
+}
+
+
+/**
+ * Get nested value from object using dot notation
+ *
+ * Supports both nested objects and flat keys with dots in them.
+ * First tries the path as a flat key, then tries nested lookup.
+ *
+ * @param obj - Object to search
+ * @param path - Dot-separated path (e.g., "result.violations.total")
+ * @returns Value at path, or undefined if not found
+ */
+export function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  // First try as a flat key (handles attributes like 'result.violations.total')
+  if (path in obj) {
+    return obj[path];
+  }
+
+  // Then try as nested path
+  const keys = path.split('.');
+  let current: unknown = obj;
+
+  for (const key of keys) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    if (typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+
+  return current;
+}
+
+/**
+ * Set nested value in object using dot notation
+ *
+ * @param obj - Object to modify
+ * @param path - Dot-separated path (e.g., "result.violations.total")
+ * @param value - Value to set
+ */
+export function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const keys = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (current[key] === undefined || typeof current[key] !== 'object') {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+
+  const lastKey = keys[keys.length - 1];
+  current[lastKey] = value;
+}
+
+/**
+ * Compute aggregate values from events
+ *
+ * Provides common aggregations like counts, totals, averages, etc.
+ * that can be used in scenario conditions and templates.
+ *
+ * @param events - Collected OTEL events
+ * @returns Aggregate values
+ */
+export function computeAggregates(events: OtelEvent[]): Record<string, unknown> {
+  const aggregates: Record<string, unknown> = {
+    // Event counts
+    'events.length': events.length,
+    'events.count': events.length,
+
+    // Spans
+    'spans.count': events.filter((e) => e.type === 'span').length,
+
+    // Logs
+    'logs.count': events.filter((e) => e.type === 'log').length,
+    'errorLogs.count': events.filter((e) => e.type === 'log' && (e.severityNumber ?? 0) >= 17).length,
+    'warnLogs.count': events.filter(
+      (e) => e.type === 'log' && (e.severityNumber ?? 0) >= 13 && (e.severityNumber ?? 0) <= 16
+    ).length,
+    'debugLogs.count': events.filter(
+      (e) => e.type === 'log' && (e.severityNumber ?? 0) >= 5 && (e.severityNumber ?? 0) <= 8
+    ).length,
+  };
+
+  // Extract attributes from summary/completion events for scenario matching
+  // These events contain execution-level data (not per-event varying data)
+  // Store ONLY as flat keys to avoid conflicts with event-specific attributes
+  const summaryEventPatterns = ['.complete', '.summary', '.error', '.started'];
+  const summaryEvents = events.filter((e) =>
+    summaryEventPatterns.some((pattern) => e.name.endsWith(pattern))
+  );
+
+  for (const event of summaryEvents) {
+    if (event.attributes) {
+      for (const [key, value] of Object.entries(event.attributes)) {
+        // Store only in flat structure to match event attribute keys
+        // This prevents nested structures from shadowing event-specific attributes
+        aggregates[key] = value;
+      }
+    }
+  }
+
+  return aggregates;
+}