@principal-ai/subsystems-core 0.29.0

package/dist/types/index.d.ts

@@ -0,0 +1,352 @@
+/**
+ * Core type definitions for the Principal View Framework
+ * Based on GENERIC_GRAPH_PANEL_DESIGN.md
+ */
+/**
+ * Represents any valid JSON value
+ * Used for data that needs to be serialized/deserialized (events, telemetry, etc.)
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * JSON object type - a record with JSON-serializable values
+ */
+export type JsonObject = Record<string, JsonValue>;
+/**
+ * Runtime data/properties for a graph node
+ * Must conform to the schema defined in NodeTypeDefinition.dataSchema
+ */
+export type NodeData = JsonObject;
+/**
+ * Runtime data/properties for a graph edge
+ * Must conform to the schema defined in EdgeTypeDefinition.dataSchema
+ */
+export type EdgeData = JsonObject;
+/**
+ * Additional metadata attached to events for observability/debugging
+ * Examples: source location, stack trace, timing info, state transition details, etc.
+ */
+export type EventMetadata = JsonObject;
+/**
+ * Validation constraints for expected events
+ * Key-value pairs that define expected properties and their values
+ */
+export type ValidationConstraints = JsonObject;
+export interface GraphConfiguration {
+    /** Metadata about the system being visualized */
+    metadata: {
+        name: string;
+        description?: string;
+    };
+    /** Node type definitions */
+    nodeTypes: Record<string, NodeTypeDefinition>;
+    /** Edge type definitions */
+    edgeTypes: Record<string, EdgeTypeDefinition>;
+    /** Allowed connections between node types */
+    allowedConnections: ConnectionRule[];
+    /** Optional validation rules */
+    validation?: ValidationRules;
+    /** Display preferences */
+    display?: DisplayConfiguration;
+    /** Global state definitions (fallback for nodes without specific states) */
+    states?: Record<string, {
+        color?: string;
+        icon?: string;
+        label?: string;
+    }>;
+}
+export interface NodeTypeDefinition {
+    /** Description of this node type (required) */
+    description: string;
+    /** Visual representation */
+    shape: 'circle' | 'rectangle' | 'hexagon' | 'diamond' | 'custom';
+    icon?: string;
+    /** Fill color (used as primary node color) */
+    color?: string;
+    /** Stroke/border color */
+    stroke?: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Data schema for this node type */
+    dataSchema: {
+        [field: string]: {
+            type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            required?: boolean;
+            displayInLabel?: boolean;
+        };
+    };
+    /** State definitions */
+    states?: Record<string, {
+        color?: string;
+        icon?: string;
+        label?: string;
+    }>;
+    /** Layout hints */
+    layout?: {
+        layer?: number;
+        cluster?: string;
+    };
+}
+export interface EdgeTypeDefinition {
+    /** Visual style */
+    style: 'solid' | 'dashed' | 'dotted' | 'animated';
+    color?: string;
+    width?: number;
+    directed?: boolean;
+    animated?: boolean;
+    /** Edge label configuration */
+    label?: {
+        field?: string;
+        position?: 'start' | 'middle' | 'end';
+    };
+    /** Animation configuration */
+    animation?: {
+        type: 'flow' | 'pulse' | 'particle' | 'glow';
+        duration?: number;
+        color?: string;
+    };
+    /** Data schema for edge metadata - fields to display when edge is clicked */
+    dataSchema?: {
+        [field: string]: {
+            type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            label?: string;
+            displayInInfo?: boolean;
+        };
+    };
+}
+export interface ConnectionRule {
+    from: string;
+    to: string;
+    via: string;
+    /** Optional constraints */
+    constraints?: {
+        maxInstances?: number;
+        bidirectional?: boolean;
+        exclusive?: boolean;
+    };
+}
+export interface ValidationRules {
+    /** State transition rules per node type */
+    stateTransitions?: Record<string, Array<{
+        from: string;
+        to: string[];
+    }>>;
+    /** Global constraints */
+    constraints?: Array<{
+        id: string;
+        description: string;
+        check: string;
+        severity: 'info' | 'warning' | 'error';
+    }>;
+    /** Cardinality rules */
+    cardinality?: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+}
+export interface DisplayConfiguration {
+    /** Default layout algorithm */
+    layout: 'hierarchical' | 'force-directed' | 'circular' | 'manual';
+    /** Color scheme */
+    theme?: {
+        primary?: string;
+        success?: string;
+        warning?: string;
+        danger?: string;
+        info?: string;
+    };
+    /** Animation preferences */
+    animations?: {
+        enabled?: boolean;
+        speed?: number;
+    };
+}
+export interface GraphEvent {
+    /** Unique event ID */
+    id: string;
+    /** Event type (user-defined) */
+    type: string;
+    /** When this event occurred */
+    timestamp: number;
+    /** Event category */
+    category: 'node' | 'edge' | 'state' | 'data' | 'system';
+    /** Event operation */
+    operation: 'create' | 'update' | 'delete' | 'animate';
+    /** Event payload */
+    payload: NodeEvent | EdgeEvent | StateEvent | DataEvent | SystemEvent;
+    /** Whether this event was expected */
+    expected?: boolean;
+    /** Optional metadata */
+    metadata?: {
+        source?: string;
+        tags?: string[];
+        description?: string;
+    };
+}
+export interface NodeEvent {
+    operation: 'create' | 'update' | 'delete';
+    nodeId: string;
+    nodeType: string;
+    data?: NodeData;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+export interface EdgeEvent {
+    operation: 'create' | 'update' | 'delete' | 'animate';
+    edgeId: string;
+    edgeType: string;
+    from: string;
+    to: string;
+    data?: EdgeData;
+    animation?: {
+        duration?: number;
+        direction?: 'forward' | 'backward' | 'bidirectional';
+    };
+}
+export interface StateEvent {
+    nodeId: string;
+    previousState?: string;
+    newState: string;
+    data?: EventMetadata;
+}
+export interface DataEvent {
+    targetId: string;
+    targetType: 'node' | 'edge';
+    updates: JsonObject;
+}
+export interface SystemEvent {
+    action: 'reset' | 'pause' | 'resume' | 'snapshot';
+    data?: JsonValue;
+}
+export interface EventStream {
+    /** Configuration (emitted once at start) */
+    configuration: GraphConfiguration;
+    /** Initial graph state (optional) */
+    initialState?: {
+        nodes: Array<Omit<NodeState, 'createdAt' | 'updatedAt'>>;
+        edges: Array<Omit<EdgeState, 'createdAt' | 'updatedAt'>>;
+    };
+    /** Stream of events */
+    events: GraphEvent[];
+    /** Optional expected events for validation */
+    expectedEvents?: Array<{
+        type: string;
+        constraints: ValidationConstraints;
+        timing?: {
+            minTime: number;
+            maxTime: number;
+        };
+    }>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    violations: Violation[];
+    warnings: Warning[];
+    metrics: ValidationMetrics;
+}
+export interface Violation {
+    id: string;
+    severity: 'warning' | 'error';
+    type: 'connection' | 'state' | 'cardinality' | 'constraint' | 'unexpected_event';
+    description: string;
+    event?: GraphEvent;
+    context?: {
+        nodeId?: string;
+        edgeId?: string;
+        rule?: string;
+    };
+}
+export interface Warning {
+    id: string;
+    type: string;
+    message: string;
+    event?: GraphEvent;
+}
+export interface ValidationMetrics {
+    totalEvents: number;
+    validEvents: number;
+    violations: number;
+    warnings: number;
+    unexpectedEvents: number;
+    expectedEventsMissing: number;
+}
+export interface GraphState {
+    nodes: Map<string, NodeState>;
+    edges: Map<string, EdgeState>;
+    configuration: GraphConfiguration;
+}
+export interface NodeState {
+    id: string;
+    type: string;
+    /** Display name for this node instance (required) */
+    name: string;
+    data: NodeData;
+    state?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Node width (persisted from resize operations) */
+    width?: number;
+    /** Node height (persisted from resize operations) */
+    height?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface EdgeState {
+    id: string;
+    type: string;
+    from: string;
+    to: string;
+    data?: EdgeData;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface GraphMetrics {
+    /** Node metrics */
+    nodes: {
+        total: number;
+        byType: Record<string, number>;
+        byState: Record<string, number>;
+    };
+    /** Edge metrics */
+    edges: {
+        total: number;
+        byType: Record<string, number>;
+    };
+    /** Event metrics */
+    events: {
+        total: number;
+        byCategory: Record<string, number>;
+        byType: Record<string, number>;
+        rate: number;
+    };
+    /** Validation metrics */
+    validation: {
+        violations: number;
+        warnings: number;
+        unexpectedEvents: number;
+        healthScore: number;
+    };
+    /** Performance metrics */
+    performance: {
+        renderTime: number;
+        eventProcessingTime: number;
+        layoutTime: number;
+    };
+}
+export * from './path-based-config';
+export * from './library';
+export * from './otel';
+export * from './resource-match';
+export * from './canvas-scope';
+export * from './audit';
+export * from './dashboard';
+export * from './auxiliary';
+export * from './subsystem-model';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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

package/dist/types/index.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Core type definitions for the Principal View Framework
+ * Based on GENERIC_GRAPH_PANEL_DESIGN.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// Path-Based Configuration Types (Milestone 1 & 2)
+// ============================================================================
+__exportStar(require("./path-based-config"), exports);
+// ============================================================================
+// Component Library Types
+// ============================================================================
+__exportStar(require("./library"), exports);
+// ============================================================================
+// OpenTelemetry and Resource Matching Types
+// ============================================================================
+__exportStar(require("./otel"), exports);
+__exportStar(require("./resource-match"), exports);
+__exportStar(require("./canvas-scope"), exports);
+__exportStar(require("./audit"), exports);
+__exportStar(require("./dashboard"), exports);
+__exportStar(require("./auxiliary"), exports);
+__exportStar(require("./subsystem-model"), exports);
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAkbH,+EAA+E;AAC/E,mDAAmD;AACnD,+EAA+E;AAE/E,sDAAoC;AAEpC,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E,4CAA0B;AAE1B,+EAA+E;AAC/E,4CAA4C;AAC5C,+EAA+E;AAE/E,yCAAuB;AACvB,mDAAiC;AACjC,iDAA+B;AAC/B,0CAAwB;AACxB,8CAA4B;AAC5B,8CAA4B;AAC5B,oDAAkC"}

package/dist/types/library.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Component Library Types
+ *
+ * Defines the structure for component libraries (.yaml/.json files)
+ * that contain reusable node and edge type definitions.
+ *
+ * Libraries are separate from canvas files:
+ * - Canvas files (.canvas) = actual graph layouts that get rendered
+ * - Library files (.yaml/.json) = collections of reusable type definitions
+ *
+ * When a user adds a component from the library to a canvas,
+ * the type definition gets embedded into the node's `pv` field.
+ */
+import type { PVEventSchema } from './canvas';
+/**
+ * Definition for an instrumentation scope
+ *
+ * Describes a scope with its color and optional metadata.
+ * Used for consistent visual representation across canvases.
+ *
+ * @deprecated Scope visual metadata is now defined in .scopes.canvas files using OtelScopeNode type.
+ * This type is kept for backward compatibility during migration but will be removed in a future version.
+ * Use .scopes.canvas files instead of the top-level scopes section in library.yaml.
+ */
+export interface ScopeDefinition {
+    /** Color for nodes belonging to this scope (hex format). Required unless external. */
+    color?: string;
+    /** Icon identifier (Lucide icons) */
+    icon?: string;
+    /** Human-readable description of what this scope covers */
+    description?: string;
+    /**
+     * Mark this scope as external - defined in another library/package.
+     * External scopes don't require color (they inherit from the defining library).
+     */
+    external?: boolean;
+}
+/**
+ * Owned scopes: array of scope names that reference top-level scopes
+ *
+ * Scope definitions are declared in the top-level `scopes` section of library.yaml.
+ * Resources reference those scopes by name.
+ */
+export type OwnedScopes = string[];
+/**
+ * OTEL resource attributes for a service/component
+ *
+ * Represents the actual resource attribute values (not match patterns).
+ * These are the attributes that would be set when instrumenting the service.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/
+ */
+export interface ResourceAttributes {
+    /** Service identification (required) */
+    'service.name': string;
+    /** Service version (recommended) */
+    'service.version'?: string;
+    /** Service namespace (optional) */
+    'service.namespace'?: string;
+    /** Service instance ID (optional) */
+    'service.instance.id'?: string;
+    /** Deployment environment (recommended) */
+    'deployment.environment'?: string;
+    /** Kubernetes namespace */
+    'k8s.namespace.name'?: string;
+    /** Kubernetes deployment name */
+    'k8s.deployment.name'?: string;
+    /** Kubernetes pod name */
+    'k8s.pod.name'?: string;
+    /** Kubernetes container name */
+    'k8s.container.name'?: string;
+    /** Kubernetes node name */
+    'k8s.node.name'?: string;
+    /** Database system */
+    'db.system'?: string;
+    /** Database name */
+    'db.name'?: string;
+    /** Host name */
+    'host.name'?: string;
+    /** Host ID */
+    'host.id'?: string;
+    /** Cloud provider */
+    'cloud.provider'?: string;
+    /** Cloud region */
+    'cloud.region'?: string;
+    /** Messaging system */
+    'messaging.system'?: string;
+    /** Messaging destination name */
+    'messaging.destination.name'?: string;
+    /**
+     * Instrumentation scopes owned by this service
+     *
+     * Lists the tracer/instrumentation scope names that belong to this service.
+     * Spans from these scopes will be matched against this service's storyboards
+     * rather than looking up external registries.
+     *
+     * Scope names must reference scopes defined in the top-level `scopes` section.
+     *
+     * @example
+     * ```yaml
+     * scopes:
+     *   auth-flow:
+     *     color: "#DC2626"
+     *     description: "Authentication flow instrumentation"
+     *
+     * resources:
+     *   auth-service:
+     *     service.name: "auth-service"
+     *     owned-scopes:
+     *       - "auth-flow"
+     * ```
+     */
+    'owned-scopes'?: OwnedScopes;
+    /** Allow arbitrary OTEL resource attributes */
+    [key: string]: string | string[] | undefined;
+}
+/**
+ * Root type for a component library file (.yaml or .json).
+ *
+ * Example library.yaml:
+ * ```yaml
+ * version: "1.0.0"
+ * name: "My Service"
+ * description: "OTEL instrumentation configuration"
+ *
+ * resources:
+ *   auth-service:
+ *     service.name: "auth-service"
+ *     service.version: "1.0.0"
+ *     deployment.environment: "production"
+ *     owned-scopes:
+ *       - "auth-flow"
+ *
+ * eventSchemas:
+ *   user.login.success:
+ *     description: "User successfully logged in"
+ *     attributes:
+ *       user.id:
+ *         type: string
+ *         required: true
+ *       session.id:
+ *         type: string
+ *         required: true
+ * ```
+ *
+ * Note: Scope visual metadata (colors, icons) are now defined in .scopes.canvas files.
+ * The `owned-scopes` field in resources is used for telemetry routing only.
+ */
+export interface ComponentLibrary {
+    /** Library schema version */
+    version: string;
+    /** Library name */
+    name: string;
+    /** Library description */
+    description?: string;
+    /**
+     * Service resource registry
+     *
+     * Defines the services in this package and their expected OTEL resource attributes.
+     * Each service configures its own resources at runtime (via env vars or SDK),
+     * but declaring them here provides:
+     * - Service documentation/registry
+     * - Expected resource schema for validation
+     * - Dev instrumentation defaults
+     * - Canvas node generation
+     *
+     * The key is a service identifier (used for reference), and the value contains
+     * the OTEL resource attributes for that service.
+     *
+     * @example
+     * ```yaml
+     * resources:
+     *   payment-api:
+     *     service.name: "payment-api"
+     *     service.version: "1.0.0"
+     *     deployment.environment: "development"
+     *
+     *   payment-worker:
+     *     service.name: "payment-worker"
+     *     service.version: "1.0.0"
+     *     deployment.environment: "development"
+     * ```
+     */
+    resources?: Record<string, ResourceAttributes>;
+    /**
+     * Reusable event schema definitions
+     *
+     * Defines event schemas that can be referenced by canvas nodes via `pv.eventRef`.
+     * This promotes reusability and consistency across canvases.
+     *
+     * @example
+     * ```yaml
+     * eventSchemas:
+     *   auth.callback.started:
+     *     description: "Authentication callback initiated"
+     *     attributes:
+     *       session.id:
+     *         type: string
+     *         required: true
+     *         description: "Session identifier"
+     * ```
+     */
+    eventSchemas?: Record<string, Omit<PVEventSchema, 'name'>>;
+}
+/**
+ * Result of loading a component library
+ */
+export interface LibraryLoadResult {
+    /** Whether the library was loaded successfully */
+    success: boolean;
+    /** The loaded library (if successful) */
+    library?: ComponentLibrary;
+    /** Error message (if failed) */
+    error?: string;
+    /** Path the library was loaded from */
+    path: string;
+}
+/**
+ * Options for the library loader
+ */
+export interface LibraryLoaderOptions {
+    /** Base directory to search for library files */
+    baseDir?: string;
+    /** Custom library file name (default: "library.yaml" or "library.json") */
+    fileName?: string;
+}
+//# sourceMappingURL=library.d.ts.map

package/dist/types/library.d.ts.map

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

package/dist/types/library.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Component Library Types
+ *
+ * Defines the structure for component libraries (.yaml/.json files)
+ * that contain reusable node and edge type definitions.
+ *
+ * Libraries are separate from canvas files:
+ * - Canvas files (.canvas) = actual graph layouts that get rendered
+ * - Library files (.yaml/.json) = collections of reusable type definitions
+ *
+ * When a user adds a component from the library to a canvas,
+ * the type definition gets embedded into the node's `pv` field.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=library.js.map

package/dist/types/library.js.map

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