@principal-ai/subsystems-core 0.29.0

package/dist/types/path-based-config.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Path-based configuration extensions for Milestone 1 & 2
+ *
+ * These types extend the core GraphConfiguration to support:
+ * - Path-based log association (Milestone 1)
+ * - Action pattern refinement (Milestone 2)
+ * - Resource-based log association (OTEL integration)
+ */
+import type { ResourceMatch } from './resource-match';
+import type { JsonValue, JsonObject } from './index';
+/**
+ * Log levels (matches logger package)
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Extended node type definition with source path mapping
+ */
+export interface PathBasedNodeTypeDefinition {
+    /** Base node type properties (inherited from NodeTypeDefinition) */
+    shape: 'circle' | 'rectangle' | 'hexagon' | 'diamond' | 'custom';
+    /** Description of this node type (required) */
+    description: string;
+    icon?: string;
+    color?: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    dataSchema: {
+        [field: string]: {
+            type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            required?: boolean;
+            displayInLabel?: boolean;
+        };
+    };
+    states?: Record<string, {
+        color?: string;
+        icon?: string;
+        label?: string;
+    }>;
+    layout?: {
+        layer?: number;
+        cluster?: string;
+    };
+    /** Manual position for 'manual' layout mode */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * MILESTONE 1: Source path mapping
+     * Exact file paths for log association (glob patterns and line numbers are not supported)
+     */
+    sources?: string[];
+    /**
+     * Resource-based matching for OTEL logs
+     *
+     * When specified, logs with matching OTEL resource attributes
+     * will be routed to this node type. Takes priority over sources.
+     *
+     * @example
+     * ```typescript
+     * resourceMatch: {
+     *   'service.name': 'checkout-api',
+     *   'deployment.environment': 'production'
+     * }
+     * ```
+     */
+    resourceMatch?: ResourceMatch;
+}
+/**
+ * Extended edge definition with action-based activation (Milestone 2)
+ */
+export interface PathBasedEdgeTypeDefinition {
+    /** Base edge properties */
+    style: 'solid' | 'dashed' | 'dotted' | 'animated';
+    color?: string;
+    width?: number;
+    directed?: boolean;
+    animated?: boolean;
+    label?: {
+        field?: string;
+        position?: 'start' | 'middle' | 'end';
+    };
+    animation?: {
+        type: 'flow' | 'pulse' | 'particle' | 'glow';
+        duration?: number;
+        color?: string;
+    };
+    /** MILESTONE 2: Edge activation triggers */
+    activatedBy?: EdgeActivationTrigger[];
+}
+/**
+ * Configuration for activating edges based on component actions
+ */
+export interface EdgeActivationTrigger {
+    /** Action that triggers this edge animation */
+    action: string;
+    /** Animation type to play */
+    animation: 'flow' | 'particle' | 'pulse' | 'glow';
+    /** Animation direction */
+    direction?: 'forward' | 'backward' | 'bidirectional';
+    /** Animation duration in milliseconds */
+    duration?: number;
+}
+/**
+ * Extended graph configuration with path-based support
+ */
+export interface PathBasedGraphConfiguration {
+    metadata: {
+        name: string;
+        description?: string;
+    };
+    /** Node types with source path mapping */
+    nodeTypes: Record<string, PathBasedNodeTypeDefinition>;
+    /** Edge types with action-based activation */
+    edgeTypes: Record<string, PathBasedEdgeTypeDefinition>;
+    /** Allowed connections between node types */
+    allowedConnections: Array<{
+        from: string;
+        to: string;
+        via: string;
+        constraints?: {
+            maxInstances?: number;
+            bidirectional?: boolean;
+            exclusive?: boolean;
+        };
+    }>;
+    /** Optional validation rules */
+    validation?: JsonObject;
+    /** Display preferences */
+    display?: JsonObject;
+    /** Path-based configuration options */
+    pathBasedConfig?: PathBasedConfigOptions;
+}
+/**
+ * Configuration options for path-based log association
+ */
+export interface PathBasedConfigOptions {
+    /** Project root for normalizing paths */
+    projectRoot?: string;
+    /** Whether to enable source capture (default: true) */
+    captureSource?: boolean;
+    /** Whether to enable action pattern matching (default: false in M1, true in M2) */
+    enableActionPatterns?: boolean;
+    /** Default log level for filtering (default: 'info') */
+    logLevel?: LogLevel;
+    /** Whether to ignore logs without source information (default: false) */
+    ignoreUnsourced?: boolean;
+}
+/**
+ * Component activity event (Milestone 1)
+ * Generated when a log is associated with a component by source path
+ */
+export interface ComponentActivityEvent {
+    type: 'component-activity';
+    /** Component ID (node type) */
+    componentId: string;
+    /**
+     * Instance identifier for multi-instance components.
+     * If provided, targets a specific node instance (e.g., "client-1").
+     * If undefined, targets the node type as a whole.
+     */
+    instanceId?: string;
+    /** Timestamp of the log */
+    timestamp: number;
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Source location */
+    source: {
+        file: string;
+        line?: number;
+        column?: number;
+    };
+    /** Additional log arguments */
+    args?: JsonValue[];
+}
+/**
+ * Component action event (Milestone 2)
+ * Generated when a log matches an action pattern
+ */
+export interface ComponentActionEvent {
+    type: 'component-action';
+    /** Component ID (node type) */
+    componentId: string;
+    /**
+     * Instance identifier for multi-instance components.
+     * If provided, targets a specific node instance (e.g., "client-1").
+     * If undefined, targets the node type as a whole.
+     */
+    instanceId?: string;
+    /** Action type (from pattern) */
+    action: string;
+    /** New state (if specified in pattern) */
+    state?: string;
+    /** Timestamp of the log */
+    timestamp: number;
+    /** Extracted metadata from capture groups */
+    metadata?: JsonObject;
+    /** Source location */
+    source: {
+        file: string;
+        line?: number;
+        column?: number;
+    };
+}
+/**
+ * Edge animation event (Milestone 2)
+ * Generated when a component action triggers edge activation
+ */
+export interface EdgeAnimationEvent {
+    type: 'edge-animation';
+    /** Edge ID to animate */
+    edgeId: string;
+    /** Animation type */
+    animation: 'flow' | 'particle' | 'pulse' | 'glow';
+    /** Animation direction */
+    direction?: 'forward' | 'backward' | 'bidirectional';
+    /** Animation duration */
+    duration: number;
+    /** Timestamp */
+    timestamp: number;
+    /** Source action that triggered this */
+    triggeredBy?: {
+        componentId: string;
+        action: string;
+    };
+}
+/**
+ * Union type of all path-based events
+ */
+export type PathBasedEvent = ComponentActivityEvent | ComponentActionEvent | EdgeAnimationEvent;
+//# sourceMappingURL=path-based-config.d.ts.map

package/dist/types/path-based-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-based-config.d.ts","sourceRoot":"","sources":["../../src/types/path-based-config.ts"],"names":[],"mappings":"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"}

package/dist/types/path-based-config.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Path-based configuration extensions for Milestone 1 & 2
+ *
+ * These types extend the core GraphConfiguration to support:
+ * - Path-based log association (Milestone 1)
+ * - Action pattern refinement (Milestone 2)
+ * - Resource-based log association (OTEL integration)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=path-based-config.js.map

package/dist/types/path-based-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-based-config.js","sourceRoot":"","sources":["../../src/types/path-based-config.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}

package/dist/types/registered-trace.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Registry-aware trace types
+ *
+ * These types integrate trace data with scope-based registry lookups
+ * to provide complete matching, validation, and routing information.
+ *
+ * Design: Multi-scope aware with three-category matching results
+ * - Scenario Matches: Spans where both workflow and scenario matched
+ * - Storyboard Matches: Spans where workflow matched but no scenario (orphaned)
+ * - Unmatched Spans: Spans that didn't match any workflow
+ *
+ * See: docs/LIBRARY_TELEMETRY_AND_MATCHING.md for full design
+ */
+import type { OtelExportTraceServiceRequest } from './otel';
+import type { VersionSnapshot } from './version-registry';
+/**
+ * Resource information from OTLP trace
+ */
+export interface TraceResource {
+    /** Service identifier for routing (e.g., "http://localhost:3000" or "web-ade") */
+    serviceIdentifier: string;
+    /** Service name from resource attributes */
+    serviceName: string;
+    /** Resource-level attributes */
+    attributes?: Record<string, unknown>;
+    /** Scopes within this resource */
+    scopes: Array<{
+        /** Instrumentation scope */
+        scope: {
+            /** Scope name (e.g., "web-ade-instrumentation", "pkg:npm/@acme/auth-library") */
+            name: string;
+            /** Scope version (e.g., "1.0.0") */
+            version: string;
+            /** Scope attributes */
+            attributes?: Record<string, unknown>;
+            /** OTLP schema URL */
+            schemaUrl?: string;
+        };
+        /** Span IDs that belong to this scope */
+        spanIds: string[];
+    }>;
+}
+/**
+ * Matched span information
+ */
+export interface MatchedSpan {
+    /** Span ID */
+    spanId: string;
+    /** Parent span ID (for hierarchy) */
+    parentSpanId?: string;
+    /** Span name */
+    spanName: string;
+    /** Matched canvas node ID */
+    nodeId: string;
+    /** Start timestamp (milliseconds) */
+    timestamp: number;
+    /** Duration (milliseconds) */
+    duration: number;
+    /** Events that were matched from this span */
+    events: string[];
+    /** Span attributes */
+    attributes?: Record<string, unknown>;
+    /** Match confidence */
+    matchConfidence?: 'exact' | 'pattern' | 'wildcard';
+}
+/**
+ * Category 1: Scenario Match
+ * Spans where both workflow and scenario matched
+ */
+export interface ScenarioMatch {
+    /** Storyboard ID that matched */
+    storyboardId: string;
+    /** Storyboard name (optional, for display) */
+    storyboardName?: string;
+    /** Workflow ID that matched */
+    workflowId: string;
+    /** Workflow name (optional, for display) */
+    workflowName?: string;
+    /** Scenario ID that matched */
+    scenarioId: string;
+    /** Scope name that this match came from */
+    scopeName: string;
+    /** Scope version that this match came from */
+    scopeVersion?: string;
+    /** Spans that matched this scenario */
+    matchedSpans: MatchedSpan[];
+    /** Scenario coverage percentage (matched events / total required events) */
+    coveragePercent?: number;
+    /** Was this a full match or partial match? */
+    matchType?: 'full' | 'partial';
+}
+/**
+ * Orphaned span information
+ */
+export interface OrphanedSpan {
+    /** Span ID */
+    spanId: string;
+    /** Parent span ID (for hierarchy) */
+    parentSpanId?: string;
+    /** Span name */
+    spanName: string;
+    /** Canvas node ID that the span matched */
+    nodeId: string;
+    /** Start timestamp (milliseconds) */
+    timestamp: number;
+    /** Duration (milliseconds) */
+    duration: number;
+    /** Why did this span not match any scenario? */
+    reason: string;
+    /** Events that were observed in this span */
+    observedEvents: string[];
+    /** Events that were expected for scenarios */
+    expectedEvents?: string[];
+    /** Span attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Category 2: Storyboard Match (Workflow-Orphaned)
+ * Spans where workflow matched but events didn't match any scenario
+ */
+export interface StoryboardMatch {
+    /** Storyboard ID that matched */
+    storyboardId: string;
+    /** Storyboard name (optional, for display) */
+    storyboardName?: string;
+    /** Workflow ID that matched */
+    workflowId: string;
+    /** Workflow name (optional, for display) */
+    workflowName?: string;
+    /** Scope name that this match came from */
+    scopeName: string;
+    /** Scope version that this match came from */
+    scopeVersion?: string;
+    /** Spans that matched workflow but no scenario */
+    orphanedSpans: OrphanedSpan[];
+}
+/**
+ * Unmatched span information
+ */
+export interface UnmatchedSpan {
+    /** Span ID */
+    spanId: string;
+    /** Parent span ID (for hierarchy) */
+    parentSpanId?: string;
+    /** Span name */
+    spanName: string;
+    /** Scope name this span came from */
+    scopeName: string;
+    /** Scope version this span came from */
+    scopeVersion?: string;
+    /** Start timestamp (milliseconds) */
+    timestamp: number;
+    /** Duration (milliseconds) */
+    duration: number;
+    /** Why didn't this span match any workflow? */
+    reason: string;
+    /** Span attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Category 3: Unmatched Spans
+ * Spans that didn't match any workflow
+ */
+export interface UnmatchedSpans {
+    /** Spans that didn't match any workflow */
+    spans: UnmatchedSpan[];
+}
+/**
+ * Validation issue found during matching
+ */
+export interface ValidationIssue {
+    /** Issue severity */
+    level: 'error' | 'warning' | 'info';
+    /** Issue category */
+    category: 'registry' | 'version' | 'matching' | 'data' | 'scope';
+    /** Human-readable message */
+    message: string;
+    /** Affected span ID (if span-specific) */
+    spanId?: string;
+    /** Affected scope name (if scope-specific) */
+    scopeName?: string;
+    /** Suggested fix */
+    suggestion?: string;
+}
+/**
+ * Registry-aware trace with scope-based matching
+ *
+ * This is the primary output of the trace matching system.
+ * It contains:
+ * - Multi-resource, multi-scope trace information
+ * - Three categories of matching results
+ * - Validation issues
+ * - Original OTLP data for details
+ */
+export interface RegisteredTrace {
+    /** Unique trace ID */
+    traceId: string;
+    /** Trace name (typically root span name) */
+    name: string;
+    /** Start timestamp (milliseconds) */
+    startTime: number;
+    /** End timestamp (milliseconds) */
+    endTime: number;
+    /** Duration (milliseconds) */
+    duration: number;
+    /** Total number of spans in this trace */
+    spanCount: number;
+    /** Has any span with error status */
+    hasErrors: boolean;
+    /**
+     * Resources in this trace
+     * A trace can contain multiple resources (e.g., multiple services)
+     * Each resource can have multiple scopes (e.g., service + libraries)
+     */
+    resources: TraceResource[];
+    /**
+     * Category 1: Scenario Matches
+     * Spans where both workflow and scenario matched (✅)
+     */
+    scenarioMatches: ScenarioMatch[];
+    /**
+     * Category 2: Storyboard Matches (Workflow-Orphaned)
+     * Spans where workflow matched but events didn't match any scenario (⚠️)
+     */
+    storyboardMatches: StoryboardMatch[];
+    /**
+     * Category 3: Unmatched Spans
+     * Spans that didn't match any workflow (❌)
+     */
+    unmatchedSpans: UnmatchedSpans;
+    /** Validation issues found during matching */
+    validationIssues?: ValidationIssue[];
+    /** Reference to full OTLP data (if needed for details view) */
+    otlpData?: OtelExportTraceServiceRequest;
+}
+/**
+ * Result of a scope lookup operation
+ *
+ * Provides detailed information about why a lookup succeeded or failed,
+ * enabling better error messages and diagnostics.
+ */
+export type ScopeLookupResult = {
+    found: true;
+    snapshot: VersionSnapshot;
+} | {
+    found: false;
+    reason: 'scope_not_owned';
+    scopeName: string;
+} | {
+    found: false;
+    reason: 'no_storyboards';
+    scopeName: string;
+};
+/**
+ * Interface for storyboard registry
+ *
+ * This is the main registry interface that supports scope-based lookups.
+ * It can route to either local development registry (file-based, hot-reload)
+ * or remote registry (API-based, cached).
+ */
+export interface StoryboardRegistryInterface {
+    /**
+     * Look up schematics by scope name and version
+     *
+     * This is the primary lookup method for the new scope-based matching.
+     *
+     * For published libraries (PURL):
+     *   scopeName: "pkg:npm/@acme/auth-library"
+     *   scopeVersion: "2.1.0"
+     *
+     * For services:
+     *   scopeName: "checkout-service"
+     *   scopeVersion: "v1.2.3"
+     *   resource.attributes must contain "customer.id"
+     *
+     * Returns a ScopeLookupResult indicating success or failure with reason.
+     */
+    lookupByScope(scope: {
+        name: string;
+        version: string;
+    }, resource: {
+        attributes?: Record<string, unknown>;
+    }): Promise<ScopeLookupResult>;
+    /**
+     * List all registered scopes
+     *
+     * Returns array of scope names and their available versions.
+     */
+    listScopes(): Promise<Array<{
+        name: string;
+        versions: string[];
+    }>>;
+    /**
+     * Check if registry supports hot-reloading (local development mode)
+     */
+    supportsHotReload(): boolean;
+}
+/**
+ * Interface for trace registry matcher
+ *
+ * Converts OTLP traces to RegisteredTrace with full scope-based matching.
+ */
+export interface TraceRegistryMatcher {
+    /**
+     * Match a trace against the registry
+     *
+     * This is the main entry point for trace matching:
+     * 1. Extract scopes from OTLP trace
+     * 2. Lookup schematics for each scope from registry
+     * 3. Match spans to workflows
+     * 4. Match events to scenarios
+     * 5. Categorize results into three buckets
+     * 6. Return RegisteredTrace with all matching information
+     */
+    matchTrace(otlpData: OtelExportTraceServiceRequest): Promise<RegisteredTrace>;
+}
+/**
+ * Resource information extracted from OTLP
+ */
+export interface Resource {
+    /** Resource attributes */
+    attributes: Record<string, unknown>;
+    /** Dropped attributes count */
+    droppedAttributesCount?: number;
+}
+/**
+ * Scope information extracted from OTLP
+ */
+export interface Scope {
+    /** Scope name */
+    name: string;
+    /** Scope version */
+    version?: string;
+    /** Scope attributes */
+    attributes?: Record<string, unknown>;
+}
+//# sourceMappingURL=registered-trace.d.ts.map

package/dist/types/registered-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered-trace.d.ts","sourceRoot":"","sources":["../../src/types/registered-trace.ts"],"names":[],"mappings":"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"}

package/dist/types/registered-trace.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Registry-aware trace types
+ *
+ * These types integrate trace data with scope-based registry lookups
+ * to provide complete matching, validation, and routing information.
+ *
+ * Design: Multi-scope aware with three-category matching results
+ * - Scenario Matches: Spans where both workflow and scenario matched
+ * - Storyboard Matches: Spans where workflow matched but no scenario (orphaned)
+ * - Unmatched Spans: Spans that didn't match any workflow
+ *
+ * See: docs/LIBRARY_TELEMETRY_AND_MATCHING.md for full design
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=registered-trace.js.map

package/dist/types/registered-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered-trace.js","sourceRoot":"","sources":["../../src/types/registered-trace.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG"}