@principal-ai/subsystems-core 0.29.0

package/src/matchers/SpanMatcher.ts

@@ -0,0 +1,381 @@
+/**
+ * SpanMatcher
+ *
+ * Efficiently matches incoming OTEL spans to canvas nodes based on
+ * declarative matching criteria defined in node metadata.
+ *
+ * Implements the OTEL Span Matching specification from:
+ * .principal-views/OTEL-SPAN-MATCHING.md
+ */
+
+import type { ExtendedCanvas, PVOtelExtension } from '../types/canvas';
+import { isOtelNode, isStandardCanvasNode } from '../types/canvas';
+import type { OtelSpanData, OtelResourceData } from '../types/otel';
+import {
+  getAttributeValue,
+  flattenResourceAttributes,
+  parseNanoTime,
+  getSpanDuration,
+} from '../types/otel';
+
+/**
+ * Compiled matching rule for a single canvas node
+ */
+interface CompiledMatchRule {
+  nodeId: string;
+  resourceMatchers: ResourceMatcher[];
+  spanMatchers: SpanMatcherFn;
+}
+
+/**
+ * Resource attribute matcher function
+ */
+type ResourceMatcher = (resourceAttrs: Record<string, string>) => boolean;
+
+/**
+ * Span matcher function
+ */
+type SpanMatcherFn = (span: OtelSpanData) => boolean;
+
+/**
+ * Match result containing matched node IDs and metadata
+ */
+export interface SpanMatchResult {
+  /** IDs of nodes that matched this span */
+  matchedNodeIds: string[];
+  /** Timestamp extracted from span (milliseconds since epoch) */
+  timestamp: number;
+  /** Span duration in milliseconds */
+  duration: number;
+}
+
+/**
+ * SpanMatcher
+ *
+ * Efficiently matches incoming OTEL spans to canvas nodes based on
+ * declarative matching criteria defined in node metadata.
+ *
+ * @example
+ * ```typescript
+ * const canvas = loadCanvas('checkout-flow.otel.canvas.json');
+ * const matcher = new SpanMatcher(canvas);
+ *
+ * // Later, when spans arrive:
+ * const result = matcher.matchSpan(span, resource);
+ * if (result.matchedNodeIds.length > 0) {
+ *   console.log('Matched nodes:', result.matchedNodeIds);
+ * }
+ * ```
+ */
+export class SpanMatcher {
+  private rules: CompiledMatchRule[] = [];
+
+  /**
+   * Create a new SpanMatcher for a canvas
+   *
+   * @param canvas Canvas with nodes containing OTEL matching criteria
+   */
+  constructor(canvas: ExtendedCanvas) {
+    this.rules = this.compileRules(canvas);
+  }
+
+  /**
+   * Pre-compile matching rules from canvas nodes
+   *
+   * This is done once at initialization for performance.
+   */
+  private compileRules(canvas: ExtendedCanvas): CompiledMatchRule[] {
+    const rules: CompiledMatchRule[] = [];
+
+    if (!canvas.nodes) return rules;
+
+    for (const node of canvas.nodes) {
+      // Get OTEL metadata from either OTEL nodes (top-level) or standard nodes (pv.otel)
+      let otel: PVOtelExtension | undefined;
+
+      if (isOtelNode(node) && node.otel) {
+        otel = node.otel as PVOtelExtension;
+      } else if (isStandardCanvasNode(node) && node.pv?.otel) {
+        otel = node.pv.otel as PVOtelExtension;
+      }
+
+      if (!otel) continue;
+
+      const rule: CompiledMatchRule = {
+        nodeId: node.id,
+        resourceMatchers: [],
+        spanMatchers: () => true, // Default: match all spans (will be overridden if spanMatch is specified)
+      };
+
+      // Compile resource matchers
+      if (otel.resourceMatch) {
+        rule.resourceMatchers.push(
+          this.compileResourceMatcher(otel.resourceMatch)
+        );
+      }
+
+      // Compile span matchers
+      if (otel.spanMatch) {
+        const spanMatcherFns: SpanMatcherFn[] = [];
+
+        // Span name matcher
+        if (otel.spanMatch.name) {
+          spanMatcherFns.push(
+            this.compileSpanNameMatcher(otel.spanMatch.name)
+          );
+        }
+
+        // Span kind matcher
+        if (otel.spanMatch.kind) {
+          spanMatcherFns.push(
+            this.compileSpanKindMatcher(otel.spanMatch.kind)
+          );
+        }
+
+        // Span attributes matcher
+        if (otel.spanMatch.attributes) {
+          spanMatcherFns.push(
+            this.compileSpanAttributesMatcher(otel.spanMatch.attributes)
+          );
+        }
+
+        // Span event matcher
+        if (otel.spanMatch.event) {
+          spanMatcherFns.push(
+            this.compileSpanEventMatcher(otel.spanMatch.event)
+          );
+        }
+
+        // Combine all span matchers with AND logic
+        rule.spanMatchers = (span: OtelSpanData) => {
+          return spanMatcherFns.every((matcher) => matcher(span));
+        };
+      }
+
+      // Only add rule if it has at least one matcher
+      if (rule.resourceMatchers.length > 0 || rule.spanMatchers.length > 0) {
+        rules.push(rule);
+      }
+    }
+
+    return rules;
+  }
+
+  /**
+   * Compile resource attribute matcher
+   */
+  private compileResourceMatcher(
+    resourceMatch: Record<string, string | string[]>
+  ): ResourceMatcher {
+    return (resourceAttrs: Record<string, string>) => {
+      // All specified attributes must match (AND logic)
+      return Object.entries(resourceMatch).every(([key, pattern]) => {
+        const value = resourceAttrs[key];
+        if (!value) return false;
+
+        if (Array.isArray(pattern)) {
+          // Match any of the patterns (OR within the array)
+          return pattern.some((p) => this.matchPattern(value, p));
+        }
+
+        return this.matchPattern(value, pattern);
+      });
+    };
+  }
+
+  /**
+   * Compile span name matcher
+   */
+  private compileSpanNameMatcher(
+    namePattern: string | string[]
+  ): SpanMatcherFn {
+    const patterns = Array.isArray(namePattern) ? namePattern : [namePattern];
+
+    return (span: OtelSpanData) => {
+      return patterns.some((pattern) => this.matchPattern(span.name, pattern));
+    };
+  }
+
+  /**
+   * Compile span kind matcher
+   */
+  private compileSpanKindMatcher(
+    kindPattern: string | string[]
+  ): SpanMatcherFn {
+    const kindStrings = Array.isArray(kindPattern) ? kindPattern : [kindPattern];
+
+    // Convert string span kinds to numeric ESpanKind values
+    const kinds = kindStrings.map((k) => this.spanKindToNumber(k));
+
+    return (span: OtelSpanData) => {
+      return kinds.includes(span.kind);
+    };
+  }
+
+  /**
+   * Convert string span kind to ESpanKind number
+   */
+  private spanKindToNumber(kind: string): number {
+    const kindMap: Record<string, number> = {
+      'SPAN_KIND_UNSPECIFIED': 0,
+      'SPAN_KIND_INTERNAL': 1,
+      'SPAN_KIND_SERVER': 2,
+      'SPAN_KIND_CLIENT': 3,
+      'SPAN_KIND_PRODUCER': 4,
+      'SPAN_KIND_CONSUMER': 5,
+    };
+    return kindMap[kind] ?? 0;
+  }
+
+  /**
+   * Compile span attributes matcher
+   */
+  private compileSpanAttributesMatcher(
+    attributesMatch: Record<string, string | string[]>
+  ): SpanMatcherFn {
+    return (span: OtelSpanData) => {
+      // All specified attributes must match (AND logic)
+      return Object.entries(attributesMatch).every(([key, pattern]) => {
+        const value = getAttributeValue(span.attributes, key);
+        if (value === undefined) return false;
+
+        const valueStr = String(value);
+
+        if (Array.isArray(pattern)) {
+          return pattern.some((p) => this.matchPattern(valueStr, p));
+        }
+
+        return this.matchPattern(valueStr, pattern);
+      });
+    };
+  }
+
+  /**
+   * Compile span event matcher
+   */
+  private compileSpanEventMatcher(
+    eventMatch: {
+      name?: string | string[];
+      attributes?: Record<string, string | string[]>;
+    }
+  ): SpanMatcherFn {
+    return (span: OtelSpanData) => {
+      if (!span.events || span.events.length === 0) return false;
+
+      // At least one event must match
+      return span.events.some((event) => {
+        // Match event name if specified
+        if (eventMatch.name) {
+          const namePatterns = Array.isArray(eventMatch.name)
+            ? eventMatch.name
+            : [eventMatch.name];
+
+          const nameMatches = namePatterns.some((pattern) =>
+            this.matchPattern(event.name, pattern)
+          );
+
+          if (!nameMatches) return false;
+        }
+
+        // Match event attributes if specified
+        if (eventMatch.attributes) {
+          const attrsMatch = Object.entries(eventMatch.attributes).every(
+            ([key, pattern]) => {
+              const value = getAttributeValue(event.attributes, key);
+              if (value === undefined) return false;
+
+              const valueStr = String(value);
+
+              if (Array.isArray(pattern)) {
+                return pattern.some((p) => this.matchPattern(valueStr, p));
+              }
+
+              return this.matchPattern(valueStr, pattern);
+            }
+          );
+
+          if (!attrsMatch) return false;
+        }
+
+        return true;
+      });
+    };
+  }
+
+  /**
+   * Match a value against a pattern
+   *
+   * Supports:
+   * - Wildcard: "*" matches anything
+   * - Glob patterns: "GET /api/*" matches "GET /api/users"
+   * - Exact match: "validateUser" matches only "validateUser"
+   */
+  private matchPattern(value: string, pattern: string): boolean {
+    // Wildcard matches everything
+    if (pattern === '*') return true;
+
+    // Exact match (fast path)
+    if (!pattern.includes('*')) {
+      return value === pattern;
+    }
+
+    // Glob pattern matching
+    // Convert glob pattern to regex
+    const regexPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+      .replace(/\*/g, '.*'); // Convert * to .*
+
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(value);
+  }
+
+  /**
+   * Match a span against all canvas nodes
+   *
+   * @param span OTEL span to match
+   * @param resource OTEL resource associated with the span
+   * @returns Match result with matched node IDs and metadata
+   */
+  public matchSpan(span: OtelSpanData, resource: OtelResourceData): SpanMatchResult {
+    const matchedNodeIds: string[] = [];
+    const resourceAttrs = flattenResourceAttributes(resource);
+
+    for (const rule of this.rules) {
+      // Check if all resource matchers pass
+      const resourceMatch = rule.resourceMatchers.every((matcher) =>
+        matcher(resourceAttrs)
+      );
+
+      // Check if span matchers pass
+      const spanMatch = rule.spanMatchers(span);
+
+      // Node matches if both resource AND span criteria match
+      if (resourceMatch && spanMatch) {
+        matchedNodeIds.push(rule.nodeId);
+      }
+    }
+
+    return {
+      matchedNodeIds,
+      timestamp: parseNanoTime(span.startTimeUnixNano),
+      duration: getSpanDuration(span),
+    };
+  }
+
+  /**
+   * Get statistics about the compiled rules
+   *
+   * Useful for debugging and performance analysis.
+   */
+  public getStats(): {
+    totalRules: number;
+    rulesWithResourceMatch: number;
+    rulesWithSpanMatch: number;
+  } {
+    return {
+      totalRules: this.rules.length,
+      rulesWithResourceMatch: this.rules.filter((r) => r.resourceMatchers.length > 0).length,
+      rulesWithSpanMatch: this.rules.filter((r) => r.spanMatchers.length > 0).length,
+    };
+  }
+}

package/src/node.ts

@@ -0,0 +1,316 @@
+/**
+ * @principal-ai/subsystems-core/node
+ * Node.js-specific exports (require Node.js runtime)
+ *
+ * This entry point includes all functionality that depends on Node.js modules
+ * such as fs, path, glob, and other Node.js-only dependencies.
+ *
+ * The main entry point ('@principal-ai/subsystems-core') exports browser-safe
+ * functionality that works in any environment. Use this /node entry point when you
+ * need Node.js-specific utilities like buildFileTreeFromDirectory.
+ */
+
+// Export all types (safe in all environments)
+export * from './types';
+
+// File-per-topic store (~/.principal/topics) — node:fs only. The browser-safe
+// topic types it reads/writes are also re-exported here for node consumers.
+export {
+  TopicStore,
+  PRINCIPAL_DIR,
+  TOPICS_DIR,
+  LEGACY_TOPICS_BLOB,
+} from './storage/topicStore';
+export type {
+  TopicIndexEntry,
+  TopicCreate,
+  TopicUpdate,
+  MigrationResult,
+} from './storage/topicStore';
+export { publishedFromDraft } from './storage/topic-types';
+export type {
+  DraftTopic,
+  PublishedTopic,
+  PublishProjection,
+  TopicStatus,
+  TopicAsset,
+  TopicCreator,
+} from './storage/topic-types';
+
+// Export core classes (Node.js processing)
+export { EventProcessor } from './EventProcessor';
+export type { ProcessingResult } from './EventProcessor';
+
+export { ValidationEngine } from './ValidationEngine';
+
+export { ConfigurationValidator } from './ConfigurationValidator';
+export type {
+  ConfigurationValidationError,
+  ConfigurationValidationResult,
+} from './ConfigurationValidator';
+
+// Export helpers
+export { GraphInstrumentationHelper } from './helpers/GraphInstrumentationHelper';
+
+// Export path-based processing (Milestone 1 & 2)
+export { PathBasedEventProcessor } from './PathBasedEventProcessor';
+export type { LogEntry } from './PathBasedEventProcessor';
+
+// Export path utilities
+export { PathMatcher } from './utils/PathMatcher';
+export { GraphConverter } from './utils/GraphConverter';
+
+// Export Canvas types and converter
+export * from './types/canvas';
+export { CanvasConverter } from './utils/CanvasConverter';
+export type { ReactFlowNode, ReactFlowEdge } from './utils/CanvasConverter';
+
+// Export telemetry event validation
+export { EventValidator, createValidatedEmitter, EventValidationError } from './telemetry/event-validator';
+export type { ValidationResult } from './telemetry/event-validator';
+
+// Export telemetry coverage analysis (re-exported from main for convenience)
+export { analyzeCoverage } from './telemetry/coverage';
+export type {
+  CoverageMetrics,
+  FileInstrumentation,
+  PackageCoverageMetrics,
+} from './telemetry/coverage';
+
+// Export code generation (Node.js only - file system operations)
+export { generateTypes, TypeScriptGenerator, generatorRegistry } from './codegen/type-generator';
+export type { CodegenOptions, CodegenResult, CodeGenerator } from './codegen/type-generator';
+
+// Export trace-to-canvas conversion
+export { traceToCanvas, traceToCanvasJson } from './utils/TraceToCanvas';
+export type {
+  TraceSpan,
+  TraceExport,
+  TraceToCanvasOptions,
+  TraceCanvasResult,
+} from './utils/TraceToCanvas';
+
+// Export session management (Event Recording System)
+export { SessionManager } from './SessionManager';
+export type {
+  SessionStatus,
+  SessionResult,
+  SessionMetadata,
+  EventSession,
+  CreateSessionOptions,
+  EndSessionOptions,
+  SessionChangeCallback,
+  SessionManagerConfig,
+} from './SessionManager';
+
+// Export event recorder service
+export { EventRecorderService } from './EventRecorderService';
+export type {
+  ProtocolMessageType,
+  ProtocolMessage,
+  SessionStartMessage,
+  SessionEndMessage,
+  LogMessage,
+  LogBatchMessage,
+  PingMessage,
+  PongMessage,
+  ErrorMessage,
+  AckMessage,
+  IncomingMessage,
+  OutgoingMessage,
+  RecordingMode,
+  EventCallback,
+  EventBatchCallback,
+  ConnectionState,
+  EventRecorderServiceConfig,
+} from './EventRecorderService';
+
+// Export configuration loading (Node.js only - file system)
+export { ConfigurationLoader } from './ConfigurationLoader';
+export type { ConfigurationFile, ConfigurationLoadResult } from './ConfigurationLoader';
+export { parseYaml, isYamlFile, getConfigNameFromFilename } from './utils/YamlParser';
+export type { YamlParseResult } from './utils/YamlParser';
+
+// Export component library support (Node.js only - file system)
+export { LibraryLoader } from './LibraryLoader';
+
+// Export event registry (for cross-canvas event lookup)
+export { EventRegistry } from './registry/EventRegistry';
+export type { EventSource } from './registry/EventRegistry';
+
+// Export opencode event retrieval (Node.js only - SQLite)
+export { OpenCodeEventStore, defaultOpenCodeDBPath } from './opencode/OpenCodeEventStore';
+export type { OpenCodeRawEvent, OpenCodeSessionEvents, OpenCodeEventRetriever, OpenCodeStoreOptions, SessionSummary, SessionListResult } from './opencode/types';
+
+// Export shared, agent-agnostic session listing/fetch/normalization (Node.js only)
+export { listAgentSessions, detectAgent, fetchRawEvents } from './opencode/agent-sessions';
+export type { AgentSessionSummary, AgentSessionMeta, SupportedSessionAgent } from './opencode/agent-sessions';
+
+// Export the frozen-fixture generator (Node.js only — runs git walk-up)
+export { buildAgentSessionFixture } from './agent-sessions/fixture';
+export type {
+  AgentSessionFixture,
+  AgentSessionFixtureMeta,
+  AgentSessionFixtureRepo,
+  AgentSessionFixtureSummary,
+  FixtureAgentSessionEvent,
+  FixtureHighlightLayer,
+  FixtureLayerItem,
+} from './agent-sessions/fixture';
+
+// Export the pure, runtime-agnostic session pipeline (no SQLite dependency)
+export {
+  NodePathNormalizationAdapter,
+  normalizeEvents,
+  normalizeEventsWithAdapter,
+  accumulateEvents,
+  collectRepositories,
+  opencodeRowsToUniversalEvents,
+} from './opencode/pipeline';
+export type { OpenCodeEventRow } from './opencode/pipeline';
+
+// Re-export FileSystemAdapter from repository-abstraction
+export type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+export { InMemoryFileSystemAdapter } from '@principal-ai/repository-abstraction';
+
+// Export rules engine (Node.js only - OpenTelemetry dependencies)
+export * from './rules';
+
+// Export workflow template system (full system including Node.js validator)
+export {
+  renderWorkflow,
+  parseTemplate,
+  ParsedTemplate,
+  selectScenario,
+  getRequiredEvents,
+  hasEventMatching,
+  computeAggregates,
+  getNestedValue,
+  setNestedValue,
+  createWorkflowValidator,
+  WorkflowValidator,
+} from './workflow';
+export type {
+  TemplateSegment,
+  WorkflowTemplate,
+  WorkflowScenario,
+  ScenarioTemplate,
+  LogTemplates,
+  FormattingOptions,
+  OtelEvent,
+  OtelSignal,
+  WorkflowContext,
+  WorkflowResult,
+  ScenarioMatchResult,
+  SpanTreeNode,
+  WorkflowValidationContext,
+  WorkflowViolation,
+  WorkflowValidationResult,
+} from './workflow';
+
+// Export canvas, workflow, and test trace discovery
+export { CanvasDiscovery } from './discovery/CanvasDiscovery';
+export type {
+  DiscoveredCanvas,
+  DiscoveredTestTrace,
+  CanvasDiscoveryResult,
+  DiscoveryOptions,
+  CanvasType,
+  TestTraceType,
+  DiscoveredCanvasWithContent,
+  DiscoveredTestTraceWithContent,
+  CanvasDiscoveryResultWithContent,
+} from './discovery/types';
+
+// Export library discovery
+export { LibraryDiscovery } from './discovery/LibraryDiscovery';
+export type {
+  DiscoveredLibrary,
+  LibraryDiscoveryResult,
+  LibraryValidationError,
+  LibraryValidationErrorType,
+} from './discovery/LibraryDiscovery';
+
+// Export execution validation
+export { ExecutionValidator, createExecutionValidator } from './execution/ExecutionValidator';
+export type {
+  ExecutionData,
+  ValidationError,
+  ExecutionValidationResult,
+} from './execution/ExecutionValidator';
+
+// Export dashboard validation
+export { DashboardValidator, createDashboardValidator } from './dashboard';
+export type {
+  DashboardValidationError,
+  DashboardValidationResult,
+  DashboardValidationContext,
+} from './dashboard';
+
+// Export execution loading (Node.js only - file system)
+export { ExecutionLoader, createExecutionLoader } from './execution/ExecutionLoader';
+export type {
+  ExecutionFile,
+  ExecutionLoadResult,
+} from './execution/ExecutionLoader';
+
+// Export scopes module (canvas validation + scope utilities)
+export {
+  ScopesCanvasValidator,
+  ScopePathIndex,
+  validateScopeNamespaceNesting,
+  DEFAULT_SCOPE_COLOR,
+  DRAFT_NODE_COLOR,
+  getScopeNames,
+  getScopeDefinition,
+  getScopeColor,
+  normalizeScopes,
+  buildScopeColorMap,
+  getAllScopeNames,
+} from './scopes';
+export type {
+  ScopesCanvasValidationContext,
+  ScopesCanvasValidationResult,
+  ScopesCanvasViolation,
+  ScopePathEntry,
+  ScopePathMatch,
+  ScopeEventsCanvasPair,
+  ValidateScopeNamespaceNestingInput,
+  NormalizedScope,
+} from './scopes';
+
+// Export auxiliary module (manifest validation for non-OTEL project regions)
+export {
+  AuxiliaryManifestValidator,
+  validateAreaScopeDisjoint,
+} from './auxiliary';
+export type {
+  AuxiliaryManifestValidationContext,
+  AuxiliaryManifestValidationResult,
+  AuxiliaryManifestViolation,
+  ValidateAreaScopeDisjointInput,
+} from './auxiliary';
+
+// Export events module (canvas validation)
+export {
+  EventsCanvasValidator,
+  ScopeEventsValidator,
+  NamespacePathIndex,
+  OtelEventPathsValidator,
+} from './events';
+export type {
+  EventsCanvasValidationContext,
+  EventsCanvasValidationResult,
+  EventsCanvasViolation,
+  ScopeEventsValidationContext,
+  ScopeEventsValidationResult,
+  ScopeEventsViolation,
+  NamespacePathEntry,
+  NamespacePathMatch,
+  EventsCanvasInput,
+  OtelCanvasInput,
+  OtelEventPathsValidationContext,
+  OtelEventPathsValidationResult,
+  OtelEventPathsViolation,
+  OtelEventPathsRuleId,
+} from './events';