@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/workflow/example.ts

@@ -1,330 +0,0 @@
-/**
- * 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

@@ -1,86 +0,0 @@
-/**
- * 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

@@ -1,253 +0,0 @@
-/**
- * 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;
-}