@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/types/index.ts

@@ -1,460 +1,7 @@
 /**
- * Core type definitions for the Principal View Framework
- * Based on GENERIC_GRAPH_PANEL_DESIGN.md
+ * Public type surface for @principal-ai/subsystems-core.
+ * Canvas / OTEL graph types were removed; this package is subsystem models +
+ * agent-session tooling (see /node and /pipeline entry points).
  */
 
-// ============================================================================
-// JSON-Serializable Types
-// ============================================================================
-
-/**
- * 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>;
-
-// ============================================================================
-// Domain-Specific Type Aliases
-// ============================================================================
-
-/**
- * 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;
-
-// ============================================================================
-// Graph Configuration Types
-// ============================================================================
-
-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; // Node type
-  to: string; // Node type
-  via: string; // Edge type
-
-  /** 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;
-  };
-}
-
-// ============================================================================
-// Event System Types
-// ============================================================================
-
-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;
-}
-
-// ============================================================================
-// Event Stream Protocol
-// ============================================================================
-
-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 };
-  }>;
-}
-
-// ============================================================================
-// Validation Types
-// ============================================================================
-
-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;
-}
-
-// ============================================================================
-// Graph State Types
-// ============================================================================
-
-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;
-}
-
-// ============================================================================
-// Metrics Types
-// ============================================================================
-
-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;
-  };
-}
-
-// ============================================================================
-// Path-Based Configuration Types (Milestone 1 & 2)
-// ============================================================================
-
-export * from './path-based-config';
-
-// ============================================================================
-// Component Library Types
-// ============================================================================
-
-export * from './library';
-
-// ============================================================================
-// OpenTelemetry and Resource Matching Types
-// ============================================================================
-
-export * from './otel';
-export * from './resource-match';
-export * from './canvas-scope';
-export * from './audit';
-export * from './dashboard';
-export * from './auxiliary';
 export * from './subsystem-model';

package/src/types/subsystem-model.ts

@@ -17,7 +17,8 @@
  */
 
 /** What the node IS as a declaration. `module` is not an authored construct —
- *  a module is its own subsystem. */
+ *  a module is its own subsystem. `custom_entity` is an authored actor
+ *  (Person / agent / queue), not code. */
 export type SubsystemConstruct =
   | 'class'
   | 'function'
@@ -26,11 +27,19 @@ export type SubsystemConstruct =
   | 'type_alias'
   | 'enum'
   | 'store'
-  | 'external';
+  | 'external'
+  | 'custom_entity';
 
 /** Where the node sits in the topology, orthogonal to construct. */
 export type SubsystemComponentRole = 'entry' | 'service';
 
+/**
+ * Actor kind for `construct: custom_entity` (open string).
+ * Examples: `Person`, `agent`, `queue`, `slack-channel`.
+ * Only meaningful on custom entities.
+ */
+export type SubsystemEntityKind = string;
+
 /**
  * Framework that owns a stereotype vocabulary (open string).
  * Examples: `react`, `vue`, `nestjs`, `django`, `spring`.
@@ -191,6 +200,22 @@ export interface SubsystemStoreDeclaration {
   properties: SubsystemPropertyInfo[];
 }
 
+/** A single authored attribute on a custom entity — free-form key/value. */
+export interface SubsystemCustomEntityAttribute {
+  key: string;
+  value: string;
+}
+
+/**
+ * Declaration for `construct: custom_entity` (an actor — Person/agent/queue).
+ * Authored, never extracted: there is no backing source declaration.
+ * `attributes` is authored key/value (e.g. `slack`, `permission`, `level`).
+ */
+export interface SubsystemCustomEntityDeclaration {
+  kind: 'custom_entity';
+  attributes: SubsystemCustomEntityAttribute[];
+}
+
 /** Structured declaration shape of a construct. */
 export type SubsystemConstructDeclaration =
   | SubsystemClassDeclaration
@@ -199,7 +224,8 @@ export type SubsystemConstructDeclaration =
   | SubsystemTypeDeclaration
   | SubsystemModuleDeclaration
   | SubsystemExternalDeclaration
-  | SubsystemStoreDeclaration;
+  | SubsystemStoreDeclaration
+  | SubsystemCustomEntityDeclaration;
 
 /** A component node — the named unit, construct-tagged. */
 export interface SubsystemComponent {
@@ -226,6 +252,16 @@ export interface SubsystemComponent {
   process?: string;
   /** Code identity — real declaration in `file` when set. */
   symbol?: string;
+  /**
+   * Actor kind for `construct: custom_entity` (e.g. `Person`, `agent`,
+   * `queue`), rendered as the node badge. Ignored on code constructs.
+   */
+  entityKind?: SubsystemEntityKind;
+  /**
+   * Node + declaration accent override (hex). Wins over the construct-derived
+   * color. Typically used to theme a custom entity (agent, queue).
+   */
+  color?: string;
   layer?: number;
   capture?: SubsystemCapture;
   /** Structured declaration shape of the construct (params, members, …). */

package/dist/ConfigurationLoader.d.ts

@@ -1,76 +0,0 @@
-/**
- * Configuration loader for managing multiple graph configurations
- *
- * Supports loading configurations from the .principal-views/ folder using the adapter pattern
- * for environment-agnostic file operations.
- */
-import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
-import type { PathBasedGraphConfiguration } from './types/path-based-config';
-/**
- * Represents a single configuration file
- */
-export interface ConfigurationFile {
-    /** Configuration name (filename without extension) */
-    name: string;
-    /** Full path to the configuration file */
-    path: string;
-    /** Parsed configuration data */
-    config: PathBasedGraphConfiguration;
-}
-/**
- * Result of loading all configurations
- */
-export interface ConfigurationLoadResult {
-    /** Successfully loaded configurations */
-    configs: ConfigurationFile[];
-    /** Errors encountered during loading */
-    errors: Array<{
-        file: string;
-        error: string;
-    }>;
-}
-/**
- * Loader for managing multiple graph configurations from .principal-views/ folder
- */
-export declare class ConfigurationLoader {
-    private fsAdapter;
-    private static readonly CONFIG_DIR;
-    constructor(fsAdapter: FileSystemAdapter);
-    /**
-     * Check if the .principal-views/ configuration directory exists
-     *
-     * @param baseDir - Base directory to search from
-     * @returns True if .principal-views/ directory exists
-     */
-    hasConfigDirectory(baseDir: string): Promise<boolean>;
-    /**
-     * List all available configuration names in .principal-views/ folder
-     *
-     * @param baseDir - Base directory containing .principal-views/ folder
-     * @returns Array of configuration names (without extensions)
-     */
-    listConfigurations(baseDir: string): Promise<string[]>;
-    /**
-     * Load a specific configuration by name
-     *
-     * @param name - Configuration name (without extension)
-     * @param baseDir - Base directory containing .principal-views/ folder
-     * @returns Configuration file or null if not found/invalid
-     */
-    loadByName(name: string, baseDir: string): Promise<ConfigurationFile | null>;
-    /**
-     * Load all configurations from .principal-views/ folder
-     *
-     * @param baseDir - Base directory containing .principal-views/ folder
-     * @returns Result containing all loaded configs and any errors
-     */
-    loadAll(baseDir: string): Promise<ConfigurationLoadResult>;
-    /**
-     * Get the configuration directory path
-     *
-     * @param baseDir - Base directory
-     * @returns Full path to .principal-views/ directory
-     */
-    getConfigDirectoryPath(baseDir: string): string;
-}
-//# sourceMappingURL=ConfigurationLoader.d.ts.map

package/dist/ConfigurationLoader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ConfigurationLoader.d.ts","sourceRoot":"","sources":["../src/ConfigurationLoader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAG7E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,MAAM,EAAE,2BAA2B,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,wCAAwC;IACxC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAGlB,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAsB;gBAEpC,SAAS,EAAE,iBAAiB;IAEhD;;;;;OAKG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3D;;;;;OAKG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAW5D;;;;;;OAMG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkClF;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAwDhE;;;;;OAKG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAGhD"}