@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/telemetry/event-validator.ts

@@ -1,312 +0,0 @@
-/**
- * Event Validator
- *
- * Type-safe telemetry event validation against canvas event schemas.
- * Ensures that emitted events match the schema defined in the canvas.
- */
-
-import type { ExtendedCanvas, PVEventSchema } from '../types/canvas';
-import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
-import type { ComponentLibrary } from '../types/library';
-import type { JsonValue, JsonObject } from '../types';
-
-/**
- * Validation error for telemetry events
- */
-export class EventValidationError extends Error {
-  constructor(
-    public eventName: string,
-    public nodeId: string,
-    public errors: string[]
-  ) {
-    super(`Event validation failed for '${eventName}' on node '${nodeId}':\n${errors.join('\n')}`);
-    this.name = 'EventValidationError';
-  }
-}
-
-/**
- * Validation result
- */
-export interface ValidationResult {
-  valid: boolean;
-  errors: string[];
-}
-
-/**
- * Event validator that checks events against canvas schema
- */
-export class EventValidator {
-  private eventSchemasByNode: Map<string, PVEventSchema> = new Map();
-  private eventSchemasByName: Map<string, PVEventSchema> = new Map();
-  private nodeIdsByBaseId: Map<string, Set<string>> = new Map();
-  private library?: ComponentLibrary;
-
-  constructor(canvas: ExtendedCanvas, library?: ComponentLibrary) {
-    this.library = library;
-    this.indexEventSchemas(canvas);
-  }
-
-  /**
-   * Index all event schemas from canvas nodes
-   */
-  private indexEventSchemas(canvas: ExtendedCanvas) {
-    if (!canvas.nodes) return;
-
-    for (const node of canvas.nodes) {
-      let eventSchema: PVEventSchema | undefined;
-
-      // Check OTEL event node (top-level event/eventRef)
-      if (isOtelEventNode(node)) {
-        if (node.event) {
-          eventSchema = node.event;
-        } else if (node.eventRef) {
-          eventSchema = this.resolveLibraryEvent(node.eventRef);
-          if (!eventSchema) {
-            console.warn(
-              `Node '${node.id}' references unknown library event '${node.eventRef}'`
-            );
-            continue;
-          }
-        }
-      }
-      // Check standard node (pv.event/pv.eventRef)
-      else if (isStandardCanvasNode(node)) {
-        if (node.pv?.event) {
-          eventSchema = node.pv.event;
-        } else if (node.pv?.eventRef) {
-          eventSchema = this.resolveLibraryEvent(node.pv.eventRef);
-          if (!eventSchema) {
-            console.warn(
-              `Node '${node.id}' references unknown library event '${node.pv.eventRef}'`
-            );
-            continue;
-          }
-        }
-      }
-
-      if (eventSchema) {
-        // Index by node ID
-        this.eventSchemasByNode.set(node.id, eventSchema);
-
-        // Index by event name
-        this.eventSchemasByName.set(eventSchema.name, eventSchema);
-
-        // Index by base node ID (strip numeric suffixes like '-2', '-3')
-        const baseId = node.id.replace(/-\d+$/, '');
-        if (!this.nodeIdsByBaseId.has(baseId)) {
-          this.nodeIdsByBaseId.set(baseId, new Set());
-        }
-        this.nodeIdsByBaseId.get(baseId)!.add(node.id);
-      }
-    }
-  }
-
-  /**
-   * Resolve an event schema from library by event name
-   */
-  private resolveLibraryEvent(eventName: string): PVEventSchema | undefined {
-    if (!this.library?.eventSchemas) {
-      return undefined;
-    }
-
-    const librarySchema = this.library.eventSchemas[eventName];
-    if (!librarySchema) {
-      return undefined;
-    }
-
-    // Convert library schema (without name) to full PVEventSchema
-    return {
-      name: eventName,
-      description: librarySchema.description,
-      attributes: librarySchema.attributes,
-    };
-  }
-
-  /**
-   * Validate an event against the schema for a specific node
-   */
-  validate(
-    nodeId: string,
-    eventName: string,
-    attributes: JsonObject
-  ): ValidationResult {
-    const errors: string[] = [];
-
-    // First try to find schema by event name (supports multiple events per component)
-    const eventSchema = this.eventSchemasByName.get(eventName);
-
-    // If not found by event name, check if the specific node has a schema
-    if (!eventSchema) {
-      // Check exact node ID first
-      const nodeSchema = this.eventSchemasByNode.get(nodeId);
-      if (nodeSchema) {
-        // Node has a schema, but this event doesn't exist anywhere
-        errors.push(`Event '${eventName}' is not defined in schema for node '${nodeId}'`);
-        return { valid: false, errors };
-      }
-
-      // Check base ID pattern (e.g., "graph-converter" for "graph-converter-1", etc.)
-      const baseId = nodeId.replace(/-\d+$/, '');
-      if (this.nodeIdsByBaseId.has(baseId)) {
-        // Component has schemas defined, but this event doesn't exist
-        errors.push(`Event '${eventName}' is not defined in schema for node '${nodeId}'`);
-        return { valid: false, errors };
-      }
-
-      // No schema defined at all - allow all events (permissive mode)
-      return { valid: true, errors: [] };
-    }
-
-    // Verify event name matches (this should always be true now, but keeping for safety)
-    if (eventSchema.name !== eventName) {
-      errors.push(`Event '${eventName}' does not match schema event name '${eventSchema.name}' for node '${nodeId}'`);
-      return { valid: false, errors };
-    }
-
-    // Validate each field in the schema
-    for (const [fieldName, fieldSchema] of Object.entries(eventSchema.attributes)) {
-      const value = attributes[fieldName];
-
-      // Check required fields
-      if (fieldSchema.required && value === undefined) {
-        errors.push(`Required field '${fieldName}' is missing`);
-        continue;
-      }
-
-      // Skip validation if field is not present and not required
-      if (value === undefined) {
-        continue;
-      }
-
-      // Validate type
-      const actualType = this.getValueType(value);
-      if (actualType !== fieldSchema.type) {
-        errors.push(
-          `Field '${fieldName}' has type '${actualType}' but schema expects '${fieldSchema.type}'`
-        );
-      }
-    }
-
-    // Check for unexpected fields (strict mode)
-    const schemaFields = new Set(Object.keys(eventSchema.attributes));
-    for (const fieldName of Object.keys(attributes)) {
-      // Allow special metadata fields
-      if (fieldName.startsWith('code.') || fieldName === 'description') {
-        continue;
-      }
-
-      if (!schemaFields.has(fieldName)) {
-        // Just a warning, not an error
-        // errors.push(`Unexpected field '${fieldName}' not in schema`);
-      }
-    }
-
-    return {
-      valid: errors.length === 0,
-      errors,
-    };
-  }
-
-  /**
-   * Get the type of a value
-   */
-  private getValueType(value: JsonValue): string {
-    if (Array.isArray(value)) return 'array';
-    if (value === null) return 'object';
-    return typeof value;
-  }
-
-  /**
-   * Get event schema for a node
-   */
-  getNodeSchema(nodeId: string): PVEventSchema | undefined {
-    return this.eventSchemasByNode.get(nodeId);
-  }
-
-  /**
-   * Get event name for a node
-   */
-  getNodeEventName(nodeId: string): string | undefined {
-    const schema = this.eventSchemasByNode.get(nodeId);
-    return schema?.name;
-  }
-
-  /**
-   * Get all event names for a node (including related nodes with same base ID)
-   */
-  getNodeEventNames(nodeId: string): string[] {
-    const baseId = nodeId.replace(/-\d+$/, '');
-    const relatedNodeIds = this.nodeIdsByBaseId.get(baseId);
-
-    if (!relatedNodeIds) {
-      const schema = this.eventSchemasByNode.get(nodeId);
-      return schema ? [schema.name] : [];
-    }
-
-    const eventNames: string[] = [];
-    for (const id of Array.from(relatedNodeIds)) {
-      const schema = this.eventSchemasByNode.get(id);
-      if (schema) {
-        eventNames.push(schema.name);
-      }
-    }
-    return eventNames;
-  }
-
-  /**
-   * Check if a node has event schema defined
-   * Supports both exact node IDs and base IDs (without numeric suffixes)
-   */
-  hasSchema(nodeId: string): boolean {
-    // Check exact match first
-    if (this.eventSchemasByNode.has(nodeId)) {
-      return true;
-    }
-
-    // Check base ID pattern (e.g., "graph-converter" matches "graph-converter-1", etc.)
-    const baseId = nodeId.replace(/-\d+$/, '');
-    return this.nodeIdsByBaseId.has(baseId);
-  }
-}
-
-/**
- * Create a validated event emitter for a specific node
- *
- * @example
- * ```typescript
- * const emit = createValidatedEmitter(validator, 'graph-converter', span);
- *
- * // Type-safe and runtime-validated
- * emit('conversion.started', {
- *   'config.nodeTypes': nodeTypes.length,
- *   'config.edgeTypes': edgeTypes.length
- * });
- * ```
- */
-export function createValidatedEmitter(
-  validator: EventValidator,
-  nodeId: string,
-  addEventFn: (eventName: string, attributes: JsonObject) => void,
-  options: { strict?: boolean } = {}
-): (eventName: string, attributes: JsonObject) => void {
-  return (eventName: string, attributes: JsonObject) => {
-    // Validate against schema
-    const result = validator.validate(nodeId, eventName, attributes);
-
-    if (!result.valid) {
-      if (options.strict !== false) {
-        // Strict mode: throw on validation errors
-        throw new EventValidationError(eventName, nodeId, result.errors);
-      } else {
-        // Permissive mode: log warnings but allow the event
-        console.warn(
-          `Event validation warnings for '${eventName}' on node '${nodeId}':`,
-          result.errors
-        );
-      }
-    }
-
-    // Emit the event
-    addEventFn(eventName, attributes);
-  };
-}

package/src/types/audit.ts

@@ -1,314 +0,0 @@
-/**
- * Log Audit Types
- *
- * Types for tracking log coverage, detecting orphaned logs, and generating
- * audit reports. Used to analyze how well a canvas maps to actual system logs.
- *
- * @see docs/CANVAS_LOG_ASSOCIATION.md for full audit documentation
- */
-
-import type { OtelResource } from './otel';
-
-/**
- * Status of a node based on log activity
- *
- * - `active`: Node is receiving logs normally
- * - `silent`: Node is defined but receiving no logs (may indicate misconfiguration)
- * - `error-heavy`: Node has unusually high error rate
- */
-export type NodeActivityStatus = 'active' | 'silent' | 'error-heavy';
-
-/**
- * Activity record for a single node
- *
- * Tracks log counts and health status for audit reporting.
- */
-export interface NodeActivity {
-  /** Node identifier */
-  nodeId: string;
-
-  /** Total log count during audit period */
-  logCount: number;
-
-  /** Error log count (severity >= ERROR) */
-  errorCount: number;
-
-  /** Warning log count (severity == WARN) */
-  warnCount: number;
-
-  /** Timestamp of last received log (null if never seen) */
-  lastSeen: number | null;
-
-  /** Computed activity status */
-  status: NodeActivityStatus;
-}
-
-/**
- * Suggested action for orphaned logs
- *
- * - `add-node`: Log appears legitimate, add a node to the canvas
- * - `fix-instrumentation`: Resource attributes look wrong, fix the source
- * - `remove`: Log appears to be test/debug artifact, should be removed
- * - `investigate`: Unable to determine, needs manual investigation
- */
-export type OrphanSuggestedAction = 'add-node' | 'fix-instrumentation' | 'remove' | 'investigate';
-
-/**
- * An orphaned log group
- *
- * Logs that matched the canvas scope but didn't match any node's
- * resourceMatch criteria. Grouped by resource signature.
- */
-export interface OrphanedLog {
-  /**
-   * Resource attributes from the orphaned logs
-   *
-   * This is the "signature" used to group similar orphans.
-   * Contains the key attributes that could be used for matching.
-   */
-  resource: OtelResource;
-
-  /** Number of logs with this resource signature */
-  count: number;
-
-  /**
-   * Sample log bodies for debugging
-   *
-   * Limited by audit config's maxSamplesPerOrphan setting.
-   */
-  samples: string[];
-
-  /** First seen timestamp */
-  firstSeen: number;
-
-  /** Last seen timestamp */
-  lastSeen: number;
-
-  /**
-   * Suggested action based on heuristics
-   *
-   * Determined by analyzing the resource attributes and log patterns.
-   */
-  suggestedAction: OrphanSuggestedAction;
-
-  /**
-   * Reason for the suggested action
-   *
-   * Human-readable explanation of why this action was suggested.
-   */
-  suggestedReason?: string;
-}
-
-/**
- * Type of audit recommendation
- *
- * - `add-node`: Add a new node to handle orphaned logs
- * - `remove-node`: Remove a node that's always silent
- * - `fix-match`: Update a node's resourceMatch criteria
- * - `check-instrumentation`: Verify OTEL instrumentation on source service
- */
-export type AuditRecommendationType =
-  | 'add-node'
-  | 'remove-node'
-  | 'fix-match'
-  | 'check-instrumentation';
-
-/**
- * Priority level for recommendations
- */
-export type AuditRecommendationPriority = 'high' | 'medium' | 'low';
-
-/**
- * Audit recommendation
- *
- * Actionable suggestion generated from audit analysis.
- */
-export interface AuditRecommendation {
-  /** Type of recommendation */
-  type: AuditRecommendationType;
-
-  /** Target node ID or resource signature */
-  target: string;
-
-  /** Human-readable reason for this recommendation */
-  reason: string;
-
-  /** Priority level */
-  priority: AuditRecommendationPriority;
-
-  /**
-   * Suggested configuration snippet (if applicable)
-   *
-   * For `add-node` recommendations, this may contain a suggested
-   * resourceMatch configuration.
-   */
-  suggestedConfig?: Record<string, unknown>;
-}
-
-/**
- * Complete audit report for a canvas
- *
- * Generated by the AuditCollector after analyzing log routing data.
- *
- * @example
- * ```typescript
- * const report: AuditReport = {
- *   canvasId: 'checkout-system',
- *   generatedAt: Date.now(),
- *   period: {
- *     start: Date.now() - 86400000,  // 24h ago
- *     end: Date.now()
- *   },
- *   summary: {
- *     totalLogs: 45231,
- *     mappedLogs: 42108,
- *     orphanedLogs: 3123,
- *     coveragePercent: 93.1
- *   },
- *   nodeActivity: [...],
- *   orphans: [...],
- *   recommendations: [...]
- * };
- * ```
- */
-export interface AuditReport {
-  /** Canvas ID this report is for */
-  canvasId: string;
-
-  /** When this report was generated */
-  generatedAt: number;
-
-  /** Time period covered by this report */
-  period: {
-    start: number;
-    end: number;
-  };
-
-  /** Summary statistics */
-  summary: {
-    /** Total logs in scope during period */
-    totalLogs: number;
-
-    /** Logs successfully routed to a node */
-    mappedLogs: number;
-
-    /** Logs in scope but not matching any node */
-    orphanedLogs: number;
-
-    /** Coverage percentage (mappedLogs / totalLogs * 100) */
-    coveragePercent: number;
-
-    /** Number of out-of-scope logs (for reference) */
-    outOfScopeLogs?: number;
-  };
-
-  /** Per-node activity breakdown */
-  nodeActivity: NodeActivity[];
-
-  /** Orphaned log groups (grouped by resource signature) */
-  orphans: OrphanedLog[];
-
-  /** Actionable recommendations */
-  recommendations: AuditRecommendation[];
-
-  /** Warnings generated during audit */
-  warnings?: string[];
-}
-
-/**
- * Result of routing a single log
- *
- * Used for real-time routing decisions and audit tracking.
- */
-export interface LogRoutingResult {
-  /**
-   * Routing outcome
-   *
-   * - `routed`: Log matched a node
-   * - `orphaned`: Log in scope but no node match
-   * - `out-of-scope`: Log doesn't match canvas scope
-   */
-  status: 'routed' | 'orphaned' | 'out-of-scope';
-
-  /** Node ID the log was routed to (if status is 'routed') */
-  nodeId?: string;
-
-  /** Match specificity score (if status is 'routed') */
-  score?: number;
-
-  /** Resource signature (if status is 'orphaned') */
-  resource?: OtelResource;
-
-  /**
-   * Matching strategy used
-   *
-   * - `resource`: Matched via resourceMatch
-   * - `path`: Matched via sources (path-based)
-   * - `explicit`: Matched via explicit annotation in log
-   */
-  matchedBy?: 'resource' | 'path' | 'explicit';
-}
-
-/**
- * Event emitted when a log is orphaned
- *
- * Can be subscribed to for real-time orphan monitoring.
- */
-export interface OrphanEvent {
-  /** Timestamp of the orphan */
-  timestamp: number;
-
-  /** Resource attributes of the orphaned log */
-  resource: OtelResource;
-
-  /** Log body (truncated if too long) */
-  body: string;
-
-  /** Canvas ID where orphan was detected */
-  canvasId: string;
-}
-
-/**
- * Create a resource signature for grouping orphans
- *
- * Extracts key attributes that should be used for matching.
- * Two logs with the same signature are considered the same "type" of orphan.
- *
- * @param resource Full resource attributes
- * @returns Signature containing key matching attributes
- */
-export function createResourceSignature(resource: OtelResource): OtelResource {
-  // Extract key attributes that would typically be used for node matching
-  const signatureKeys = [
-    'service.name',
-    'service.namespace',
-    'deployment.environment',
-    'db.system',
-    'db.name',
-    'k8s.deployment.name',
-    'k8s.namespace.name',
-    'messaging.system',
-    'messaging.destination.name',
-  ];
-
-  const signature: OtelResource = {};
-
-  for (const key of signatureKeys) {
-    if (resource[key] !== undefined) {
-      signature[key] = resource[key];
-    }
-  }
-
-  return signature;
-}
-
-/**
- * Convert a resource signature to a string key for Map/Set usage
- */
-export function signatureToKey(resource: OtelResource): string {
-  const entries = Object.entries(resource)
-    .filter(([, v]) => v !== undefined)
-    .sort(([a], [b]) => a.localeCompare(b));
-
-  return entries.map(([k, v]) => `${k}=${v}`).join('|');
-}

package/src/types/auxiliary.ts

@@ -1,63 +0,0 @@
-/**
- * Auxiliary Manifest Types
- *
- * The auxiliary manifest catalogs project regions that are *not* OTEL scopes —
- * folders like `docs/` or `.github/` that support the project but don't emit
- * telemetry. Scope paths and area paths together form a partition of the
- * accounted-for filesystem.
- *
- * The manifest is open-ended: `areas` is the first section, but the top-level
- * shape leaves room for future sibling sections (e.g. external integrations)
- * without breaking the format.
- */
-
-/**
- * One project area — a folder (or file) that supports the project outside the
- * OTEL telemetry surface.
- */
-export interface ProjectArea {
-  /**
-   * Display name. Must be unique across all areas in the manifest — used as
-   * the area's identifier in diagnostics.
-   */
-  name: string;
-
-  /**
-   * One or more repo-relative paths owned by this area. Each entry may be a
-   * folder (covers all descendants) or a specific file. Paths must not
-   * overlap other areas, and must not overlap any scope path declared in a
-   * `.scopes.canvas`.
-   */
-  paths: string[];
-
-  /**
-   * Free-text purpose. The "light documentation" — a sentence about why this
-   * folder exists.
-   */
-  description: string;
-}
-
-/**
- * The full manifest document. Persisted at
- * `.principal-views/auxiliary.manifest.json`.
- */
-export interface AuxiliaryManifest {
-  /**
-   * Optional pointer to the JSON Schema that describes this file. Lets editors
-   * give autocomplete and validation when the field is set.
-   */
-  $schema?: string;
-
-  /** Project areas declared in this manifest. */
-  areas: ProjectArea[];
-}
-
-/**
- * Type guard: true when the value plausibly conforms to `AuxiliaryManifest`.
- * Shallow check — full validation lives in `AuxiliaryManifestValidator`.
- */
-export function isAuxiliaryManifest(value: unknown): value is AuxiliaryManifest {
-  if (!value || typeof value !== 'object') return false;
-  const v = value as { areas?: unknown };
-  return Array.isArray(v.areas);
-}