cognitive-core 0.1.2 → 0.2.0

package/src/learning/healing-orchestrator.ts

@@ -0,0 +1,383 @@
+/**
+ * HealingOrchestrator — Plug-in anomaly detection and repair pattern.
+ *
+ * Inspired by ruvector's HealingOrchestrator (ruvector-dag/healing/orchestrator.rs).
+ * Runs registered anomaly detectors and repair strategies in each maintenance
+ * cycle. Detectors and strategies are push-registered via add methods.
+ *
+ * The orchestrator itself has no internal timer — `runCycle()` is called
+ * explicitly by the MaintenanceScheduler or manually by the caller.
+ */
+
+/**
+ * Health context provided to detectors and repair strategies.
+ */
+export interface HealthContext {
+  /** Total trajectories processed since last cycle */
+  trajectoriesProcessed: number;
+  /** Current experience count */
+  experienceCount: number;
+  /** Current playbook count */
+  playbookCount: number;
+  /** Recent success rate (0.0–1.0) */
+  recentSuccessRate: number;
+  /** Batches since last maintenance */
+  batchesSinceLastMaintenance: number;
+  /** Custom metrics from subsystems */
+  metrics: Record<string, number>;
+}
+
+/**
+ * An anomaly detected by a detector.
+ */
+export interface Anomaly {
+  /** Unique type identifier (e.g., 'playbook-drift', 'memory-bloat') */
+  type: string;
+  /** Severity: higher = more urgent */
+  severity: 'low' | 'medium' | 'high';
+  /** Human-readable description */
+  description: string;
+  /** Detector that found this anomaly */
+  detectorName: string;
+  /** Arbitrary data for repair strategies to use */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Result of a repair attempt.
+ */
+export interface RepairResult {
+  /** Whether the repair was successful */
+  success: boolean;
+  /** What the repair strategy did */
+  action: string;
+  /** Repair strategy name */
+  strategyName: string;
+  /** Duration in ms */
+  durationMs: number;
+}
+
+/**
+ * Result of a full healing cycle.
+ */
+export interface HealingCycleResult {
+  /** Anomalies detected in this cycle */
+  anomaliesDetected: Anomaly[];
+  /** Repair attempts and their results */
+  repairs: RepairResult[];
+  /** Total duration of the cycle in ms */
+  durationMs: number;
+  /** Timestamp */
+  timestamp: Date;
+}
+
+/**
+ * Interface for anomaly detectors.
+ * Implement this to create custom health checks.
+ */
+export interface AnomalyDetector {
+  /** Unique name for this detector */
+  readonly name: string;
+  /** Run detection and return any anomalies found */
+  detect(context: HealthContext): Promise<Anomaly[]>;
+}
+
+/**
+ * Interface for repair strategies.
+ * Implement this to create custom repair actions.
+ */
+export interface RepairStrategy {
+  /** Unique name for this strategy */
+  readonly name: string;
+  /** Check if this strategy can handle a given anomaly type */
+  canRepair(anomaly: Anomaly): boolean;
+  /** Attempt to repair the anomaly */
+  repair(anomaly: Anomaly, context: HealthContext): Promise<RepairResult>;
+}
+
+/**
+ * HealingOrchestrator — coordinates anomaly detection and repair.
+ */
+export class HealingOrchestrator {
+  private detectors: AnomalyDetector[] = [];
+  private strategies: RepairStrategy[] = [];
+  private cycleHistory: HealingCycleResult[] = [];
+  private maxHistorySize: number;
+
+  constructor(options?: { maxHistorySize?: number }) {
+    this.maxHistorySize = options?.maxHistorySize ?? 20;
+  }
+
+  /**
+   * Register an anomaly detector.
+   */
+  addDetector(detector: AnomalyDetector): void {
+    // Replace existing detector with same name
+    this.detectors = this.detectors.filter(d => d.name !== detector.name);
+    this.detectors.push(detector);
+  }
+
+  /**
+   * Unregister an anomaly detector by name.
+   */
+  removeDetector(name: string): void {
+    this.detectors = this.detectors.filter(d => d.name !== name);
+  }
+
+  /**
+   * Register a repair strategy.
+   */
+  addRepairStrategy(strategy: RepairStrategy): void {
+    this.strategies = this.strategies.filter(s => s.name !== strategy.name);
+    this.strategies.push(strategy);
+  }
+
+  /**
+   * Unregister a repair strategy by name.
+   */
+  removeRepairStrategy(name: string): void {
+    this.strategies = this.strategies.filter(s => s.name !== name);
+  }
+
+  /**
+   * Run a healing cycle.
+   *
+   * 1. Runs all registered detectors to find anomalies
+   * 2. For each anomaly, finds the first matching repair strategy
+   * 3. Executes the repair
+   */
+  async runCycle(context: HealthContext): Promise<HealingCycleResult> {
+    const start = Date.now();
+    const anomalies: Anomaly[] = [];
+    const repairs: RepairResult[] = [];
+
+    // Phase 1: Detection
+    for (const detector of this.detectors) {
+      try {
+        const detected = await detector.detect(context);
+        anomalies.push(...detected);
+      } catch (error) {
+        // Non-critical — log but continue
+        anomalies.push({
+          type: 'detector-error',
+          severity: 'low',
+          description: `Detector '${detector.name}' failed: ${error instanceof Error ? error.message : String(error)}`,
+          detectorName: detector.name,
+        });
+      }
+    }
+
+    // Sort by severity (high first)
+    const severityOrder: Record<string, number> = { high: 0, medium: 1, low: 2 };
+    anomalies.sort(
+      (a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3),
+    );
+
+    // Phase 2: Repair
+    for (const anomaly of anomalies) {
+      // Skip detector errors (not repairable)
+      if (anomaly.type === 'detector-error') continue;
+
+      for (const strategy of this.strategies) {
+        if (!strategy.canRepair(anomaly)) continue;
+
+        const repairStart = Date.now();
+        try {
+          const result = await strategy.repair(anomaly, context);
+          repairs.push(result);
+        } catch (error) {
+          repairs.push({
+            success: false,
+            action: `Failed: ${error instanceof Error ? error.message : String(error)}`,
+            strategyName: strategy.name,
+            durationMs: Date.now() - repairStart,
+          });
+        }
+
+        // Only apply first matching strategy per anomaly
+        break;
+      }
+    }
+
+    const result: HealingCycleResult = {
+      anomaliesDetected: anomalies,
+      repairs,
+      durationMs: Date.now() - start,
+      timestamp: new Date(),
+    };
+
+    this.cycleHistory.push(result);
+    if (this.cycleHistory.length > this.maxHistorySize) {
+      this.cycleHistory.shift();
+    }
+
+    return result;
+  }
+
+  /**
+   * Get cycle history for diagnostics.
+   */
+  getCycleHistory(): readonly HealingCycleResult[] {
+    return this.cycleHistory;
+  }
+
+  /**
+   * Get registered detectors.
+   */
+  getDetectors(): readonly AnomalyDetector[] {
+    return this.detectors;
+  }
+
+  /**
+   * Get registered repair strategies.
+   */
+  getRepairStrategies(): readonly RepairStrategy[] {
+    return this.strategies;
+  }
+}
+
+/**
+ * Create a HealingOrchestrator.
+ */
+export function createHealingOrchestrator(
+  options?: { maxHistorySize?: number },
+): HealingOrchestrator {
+  return new HealingOrchestrator(options);
+}
+
+// =========================================================================
+// Built-in Detectors
+// =========================================================================
+
+/**
+ * Detects when playbook success rates are consistently low,
+ * suggesting playbook drift.
+ */
+export class PlaybookDriftDetector implements AnomalyDetector {
+  readonly name = 'playbook-drift';
+  private threshold: number;
+
+  constructor(threshold = 0.3) {
+    this.threshold = threshold;
+  }
+
+  async detect(context: HealthContext): Promise<Anomaly[]> {
+    const anomalies: Anomaly[] = [];
+
+    if (
+      context.recentSuccessRate < this.threshold &&
+      context.playbookCount > 0 &&
+      context.trajectoriesProcessed >= 5
+    ) {
+      anomalies.push({
+        type: 'playbook-drift',
+        severity: 'medium',
+        description: `Recent success rate (${(context.recentSuccessRate * 100).toFixed(0)}%) is below threshold (${(this.threshold * 100).toFixed(0)}%) with ${context.playbookCount} playbooks available`,
+        detectorName: this.name,
+        data: {
+          successRate: context.recentSuccessRate,
+          playbookCount: context.playbookCount,
+        },
+      });
+    }
+
+    return anomalies;
+  }
+}
+
+/**
+ * Detects when the experience store is growing beyond capacity,
+ * suggesting aggressive pruning is needed.
+ */
+export class MemoryBloatDetector implements AnomalyDetector {
+  readonly name = 'memory-bloat';
+  private maxExperiences: number;
+  private warningRatio: number;
+
+  constructor(maxExperiences = 1000, warningRatio = 0.9) {
+    this.maxExperiences = maxExperiences;
+    this.warningRatio = warningRatio;
+  }
+
+  async detect(context: HealthContext): Promise<Anomaly[]> {
+    const anomalies: Anomaly[] = [];
+
+    if (
+      this.maxExperiences > 0 &&
+      context.experienceCount >= this.maxExperiences * this.warningRatio
+    ) {
+      const severity =
+        context.experienceCount >= this.maxExperiences ? 'high' : 'medium';
+
+      anomalies.push({
+        type: 'memory-bloat',
+        severity,
+        description: `Experience count (${context.experienceCount}) is ${severity === 'high' ? 'at' : 'approaching'} capacity (${this.maxExperiences})`,
+        detectorName: this.name,
+        data: {
+          experienceCount: context.experienceCount,
+          maxExperiences: this.maxExperiences,
+        },
+      });
+    }
+
+    return anomalies;
+  }
+}
+
+/**
+ * Detects when a custom metric exceeds a Z-score threshold,
+ * inspired by ruvector's Z-score-based outlier detection.
+ */
+export class MetricDriftDetector implements AnomalyDetector {
+  readonly name: string;
+  private metricKey: string;
+  private history: number[] = [];
+  private windowSize: number;
+  private zThreshold: number;
+
+  constructor(
+    metricKey: string,
+    options?: { windowSize?: number; zThreshold?: number },
+  ) {
+    this.name = `metric-drift:${metricKey}`;
+    this.metricKey = metricKey;
+    this.windowSize = options?.windowSize ?? 20;
+    this.zThreshold = options?.zThreshold ?? 2.0;
+  }
+
+  async detect(context: HealthContext): Promise<Anomaly[]> {
+    const value = context.metrics[this.metricKey];
+    if (value === undefined) return [];
+
+    this.history.push(value);
+    if (this.history.length > this.windowSize) {
+      this.history.shift();
+    }
+
+    if (this.history.length < 3) return [];
+
+    const mean = this.history.reduce((s, v) => s + v, 0) / this.history.length;
+    const variance =
+      this.history.reduce((s, v) => s + (v - mean) ** 2, 0) / this.history.length;
+    const std = Math.sqrt(variance);
+
+    if (std === 0) return [];
+
+    const zScore = Math.abs(value - mean) / std;
+
+    if (zScore >= this.zThreshold) {
+      return [
+        {
+          type: 'metric-drift',
+          severity: zScore >= this.zThreshold * 1.5 ? 'high' : 'medium',
+          description: `Metric '${this.metricKey}' value ${value.toFixed(2)} has z-score ${zScore.toFixed(2)} (threshold: ${this.zThreshold})`,
+          detectorName: this.name,
+          data: { metricKey: this.metricKey, value, zScore, mean, std },
+        },
+      ];
+    }
+
+    return [];
+  }
+}

package/src/learning/index.ts

@@ -11,13 +11,6 @@ export {
   type AnalyzerConfig,
 } from './analyzer.js';
 
-export {
-  LearningPipeline,
-  createLearningPipeline,
-  type ProcessResult,
-  type BatchResult,
-} from './pipeline.js';
-
 // Playbook-based learning
 export {
   PlaybookExtractor,
@@ -77,12 +70,27 @@ export {
   InMemoryTrajectorySource,
   FileTrajectorySource,
   PipelineTrajectorySource,
-  EntireTrajectorySource,
-  type EntireSynthesisOptions,
+  SessionTrajectorySource,
+  type SessionSynthesisOptions,
   DataclawTrajectorySource,
   type DataclawSourceOptions,
 } from './trajectory-sources/index.js';
 
+// Instant (hot-path) learning
+export {
+  InstantLoop,
+  createInstantLoop,
+  type InstantLoopResult,
+  type InstantLoopConfig,
+} from './instant-loop.js';
+
+// Reflexion generation
+export {
+  ReflexionGenerator,
+  createReflexionGenerator,
+  type ReflexionGeneratorConfig,
+} from './reflexion-generator.js';
+
 // Effectiveness tracking
 export {
   LearningEffectivenessTracker,
@@ -91,3 +99,51 @@ export {
   type EffectivenessMetrics,
   type PlaybookEffectivenessEntry,
 } from './effectiveness.js';
+
+// Unified learning pipeline (three-speed: immediate + batch + maintenance)
+export {
+  UnifiedLearningPipeline,
+  createUnifiedPipeline,
+  type UnifiedPipelineConfig,
+  type UnifiedPipelineFeatures,
+  type ImmediateResult,
+  type UnifiedBatchResult,
+  type UnifiedPipelineStats,
+  type EnergyEvaluation,
+  type EnergySignal,
+  type EscalationReason,
+  type MaintenanceCycleResult,
+  type MaintenanceTask,
+  type HealingCycleResult,
+  type HealthContext,
+  type AnomalyDetector,
+  type RepairStrategy,
+} from './unified-pipeline.js';
+
+// Energy evaluator (ruvector-inspired batch trigger)
+export {
+  EnergyEvaluator,
+  createEnergyEvaluator,
+  type EnergyEvaluatorConfig,
+  type LaneTransition,
+} from './energy-evaluator.js';
+
+// Maintenance scheduler (circadian-style duty-gated)
+export {
+  MaintenanceScheduler,
+  createMaintenanceScheduler,
+  type MaintenanceSchedulerConfig,
+  type MaintenanceMode,
+  type MaintenanceTaskResult,
+} from './maintenance-scheduler.js';
+
+// Healing orchestrator (plug-in detector/repair)
+export {
+  HealingOrchestrator,
+  createHealingOrchestrator,
+  PlaybookDriftDetector,
+  MemoryBloatDetector,
+  MetricDriftDetector,
+  type Anomaly,
+  type RepairResult,
+} from './healing-orchestrator.js';