@principal-ai/subsystems-core 0.29.0

package/src/telemetry/event-validator.ts

@@ -0,0 +1,312 @@
+/**
+ * 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

@@ -0,0 +1,314 @@
+/**
+ * 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

@@ -0,0 +1,63 @@
+/**
+ * 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);
+}