cognitive-core 0.1.0 → 0.2.0

package/src/learning/unified-pipeline.ts

@@ -0,0 +1,921 @@
+/**
+ * UnifiedLearningPipeline — Three-speed learning orchestrator.
+ *
+ * Consolidates InstantLoop, LearningPipeline (batch), LoopCoordinator,
+ * MetaLearner, EffectivenessTracker, and KnowledgeExtractor into a single
+ * owner that manages the full learning lifecycle.
+ *
+ * Three processing speeds (inspired by ruvector SONA):
+ *
+ *   1. **Immediate** (InstantLoop, <200ms): Fires on every trajectory.
+ *      Stores experience, bumps playbooks, extracts lightweight knowledge,
+ *      causal edges, and reflexion episodes.
+ *
+ *   2. **Batch** (cold pipeline): Triggered by energy-threshold evaluation
+ *      (not just count). Runs full analysis, playbook extraction, temporal
+ *      compression, and experience clustering.
+ *
+ *   3. **Maintenance** (circadian-gated): Runs periodically or after N batches.
+ *      Knowledge defrag, healing orchestrator, meta-strategy generation,
+ *      effectiveness reporting.
+ *
+ * The pipeline owns all components and coordinates them. Atlas delegates
+ * learning to this pipeline rather than managing components directly.
+ */
+
+import type {
+  Trajectory,
+  LearningConfig,
+  Playbook,
+} from '../types/index.js';
+import type { TrajectoryWithAnalysis } from '../types/trajectory-source.js';
+import type { MemorySystem } from '../memory/system.js';
+import type { SqlitePersistence } from '../persistence/index.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+
+// Immediate-phase components
+import { InstantLoop, type InstantLoopResult, type InstantLoopConfig } from './instant-loop.js';
+
+// Batch-phase components
+import {
+  TrajectoryAnalyzer,
+  createAnalyzer,
+  type AnalysisResult,
+} from './analyzer.js';
+import {
+  PlaybookExtractor,
+  createPlaybookExtractor,
+} from './playbook-extractor.js';
+import { KnowledgeExtractor, type ExtractionContext } from './knowledge-extractor.js';
+import { TemporalCompressor } from '../memory/temporal-compressor.js';
+import { ReasoningBank } from '../memory/reasoning-bank.js';
+import { trajectoryAnalysisTemplate } from '../workspace/templates/trajectory-analysis.js';
+import { playbookExtractionTemplate } from '../workspace/templates/playbook-extraction.js';
+
+// Meta-learning and effectiveness
+import { MetaLearner, type MetaLearnerConfig } from './meta-learner.js';
+import { LearningEffectivenessTracker } from './effectiveness.js';
+
+// Energy evaluator (batch trigger)
+import {
+  EnergyEvaluator,
+  type EnergyEvaluatorConfig,
+  type EnergyEvaluation,
+  type EnergySignal,
+  type EscalationReason,
+} from './energy-evaluator.js';
+
+// Maintenance scheduler
+import {
+  MaintenanceScheduler,
+  type MaintenanceSchedulerConfig,
+  type MaintenanceCycleResult,
+  type MaintenanceTask,
+} from './maintenance-scheduler.js';
+
+// Healing orchestrator
+import {
+  HealingOrchestrator,
+  type HealthContext,
+  type HealingCycleResult,
+  type AnomalyDetector,
+  type RepairStrategy,
+  PlaybookDriftDetector,
+  MemoryBloatDetector,
+} from './healing-orchestrator.js';
+
+// Re-export types from sub-modules for convenience
+export type {
+  EnergyEvaluation,
+  EnergySignal,
+  EscalationReason,
+  MaintenanceCycleResult,
+  MaintenanceTask,
+  HealingCycleResult,
+  HealthContext,
+  AnomalyDetector,
+  RepairStrategy,
+};
+
+// =========================================================================
+// Configuration
+// =========================================================================
+
+/**
+ * Feature flags for optional subsystems.
+ */
+export interface UnifiedPipelineFeatures {
+  /** Enable temporal compression in batch pipeline (default: true) */
+  temporalCompression?: boolean;
+  /** Enable experience clustering via ReasoningBank (default: true) */
+  reasoningBank?: boolean;
+  /** Enable reflexion episode generation (default: true) */
+  reflexion?: boolean;
+  /** Enable causal edge extraction (default: true) */
+  causalExtraction?: boolean;
+  /** Enable knowledge extraction in batch pipeline (default: true) */
+  knowledgeExtraction?: boolean;
+  /** Enable meta-learning (default: true) */
+  metaLearning?: boolean;
+  /** Enable effectiveness tracking (default: true) */
+  effectivenessTracking?: boolean;
+  /** Enable healing orchestrator with built-in detectors (default: true) */
+  healing?: boolean;
+}
+
+/**
+ * Full configuration for the UnifiedLearningPipeline.
+ */
+export interface UnifiedPipelineConfig {
+  /** Immediate-phase (InstantLoop) config */
+  instant: InstantLoopConfig;
+  /** Batch-phase config */
+  batch: {
+    learning: Partial<LearningConfig>;
+    energy: Partial<EnergyEvaluatorConfig>;
+  };
+  /** Maintenance-phase config */
+  maintenance: Partial<MaintenanceSchedulerConfig>;
+  /** Meta-learner config */
+  metaLearner: Partial<MetaLearnerConfig>;
+  /** Feature flags */
+  features: UnifiedPipelineFeatures;
+  /** Max latency warning threshold for instant loop in ms (default: 200) */
+  maxInstantLatencyMs: number;
+}
+
+const DEFAULT_UNIFIED_CONFIG: UnifiedPipelineConfig = {
+  instant: {},
+  batch: {
+    learning: {},
+    energy: {},
+  },
+  maintenance: {},
+  metaLearner: {},
+  features: {},
+  maxInstantLatencyMs: 200,
+};
+
+// =========================================================================
+// Result Types
+// =========================================================================
+
+/**
+ * Result of processing a single trajectory through the immediate phase.
+ */
+export interface ImmediateResult {
+  /** InstantLoop result */
+  instantLoop: InstantLoopResult;
+  /** Energy evaluation (did this trajectory push us toward batch?) */
+  energyEval: EnergyEvaluation;
+  /** Whether a batch was triggered by this trajectory */
+  batchTriggered: boolean;
+  /** Batch result if one was triggered */
+  batchResult?: UnifiedBatchResult;
+  /** Whether maintenance was triggered after batch */
+  maintenanceTriggered: boolean;
+  /** Maintenance result if triggered */
+  maintenanceResult?: MaintenanceCycleResult;
+}
+
+/**
+ * Result of a batch processing cycle.
+ */
+export interface UnifiedBatchResult {
+  /** Number of trajectories processed in this batch */
+  trajectoriesProcessed: number;
+  /** Playbooks extracted or updated */
+  playbooksExtracted: number;
+  /** Experiences pruned (including compression evictions) */
+  experiencesPruned: number;
+  /** Temporal compression details */
+  experiencesCompressed: {
+    promoted: number;
+    demoted: number;
+    evicted: number;
+  };
+  /** Experiences re-clustered */
+  experiencesClustered: number;
+  /** Knowledge notes extracted in batch (from KnowledgeExtractor) */
+  knowledgeExtracted: number;
+  /** Success rate of the batch */
+  successRate: number;
+  /** Escalation reasons that triggered this batch */
+  triggerReasons: EscalationReason[];
+}
+
+/**
+ * Pipeline statistics.
+ */
+export interface UnifiedPipelineStats {
+  /** Total trajectories processed (immediate) */
+  totalProcessed: number;
+  /** Total batch cycles run */
+  batchCyclesRun: number;
+  /** Total maintenance cycles run */
+  maintenanceCyclesRun: number;
+  /** Current pending count for batch */
+  pendingForBatch: number;
+  /** Batches since last maintenance */
+  batchesSinceLastMaintenance: number;
+  /** Registered maintenance tasks */
+  maintenanceTasks: string[];
+  /** Registered anomaly detectors */
+  anomalyDetectors: string[];
+  /** Registered repair strategies */
+  repairStrategies: string[];
+}
+
+// =========================================================================
+// Unified Pipeline
+// =========================================================================
+
+/**
+ * UnifiedLearningPipeline — owns all learning components and orchestrates
+ * the three-speed processing loop.
+ */
+export class UnifiedLearningPipeline {
+  // Configuration
+  private config: UnifiedPipelineConfig;
+  private learningConfig: LearningConfig;
+
+  // Immediate-phase components
+  private instantLoop: InstantLoop;
+
+  // Batch-phase components
+  private analyzer: TrajectoryAnalyzer;
+  private playbookExtractor: PlaybookExtractor;
+  private knowledgeExtractor: KnowledgeExtractor | null;
+  private temporalCompressor: TemporalCompressor | null;
+  private reasoningBank: ReasoningBank | null;
+
+  // Meta-learning and effectiveness
+  private metaLearner: MetaLearner | null = null;
+  private effectivenessTracker: LearningEffectivenessTracker | null = null;
+
+  // Orchestration
+  private energyEvaluator: EnergyEvaluator;
+  private maintenanceScheduler: MaintenanceScheduler;
+  private healingOrchestrator: HealingOrchestrator;
+
+  // State
+  private memory: MemorySystem;
+  private taskRunner: AgenticTaskRunner | null = null;
+  private accumulated: Trajectory[] = [];
+  private accumulatedAnalyses: AnalysisResult[] = [];
+  private totalProcessed = 0;
+  private batchCyclesRun = 0;
+  private maintenanceCyclesRun = 0;
+  private _onLatencyWarning: ((durationMs: number) => void) | null = null;
+
+  constructor(
+    memory: MemorySystem,
+    config?: Partial<UnifiedPipelineConfig>,
+    persistence?: SqlitePersistence,
+  ) {
+    this.config = {
+      ...DEFAULT_UNIFIED_CONFIG,
+      ...config,
+      instant: { ...DEFAULT_UNIFIED_CONFIG.instant, ...config?.instant },
+      batch: {
+        learning: { ...DEFAULT_UNIFIED_CONFIG.batch.learning, ...config?.batch?.learning },
+        energy: { ...DEFAULT_UNIFIED_CONFIG.batch.energy, ...config?.batch?.energy },
+      },
+      maintenance: { ...DEFAULT_UNIFIED_CONFIG.maintenance, ...config?.maintenance },
+      metaLearner: { ...DEFAULT_UNIFIED_CONFIG.metaLearner, ...config?.metaLearner },
+      features: { ...DEFAULT_UNIFIED_CONFIG.features, ...config?.features },
+    };
+
+    this.memory = memory;
+
+    // Resolve learning config with defaults
+    const lc = this.config.batch.learning;
+    this.learningConfig = {
+      creditStrategy: lc.creditStrategy ?? 'simple',
+      patternExtractor: lc.patternExtractor ?? 'llm',
+      minTrajectories: lc.minTrajectories ?? 10,
+      minHoursSinceLast: lc.minHoursSinceLast,
+      minSuccessRate: lc.minSuccessRate,
+      deduplicationThreshold: lc.deduplicationThreshold ?? 0.9,
+      maxExperiences: lc.maxExperiences ?? 1000,
+    };
+
+    // Immediate phase
+    this.instantLoop = new InstantLoop(memory, {
+      ...this.config.instant,
+      enableReflexion: this.config.features.reflexion ?? true,
+      enableCausalExtraction: this.config.features.causalExtraction ?? true,
+    });
+
+    // Batch phase
+    this.analyzer = createAnalyzer(this.learningConfig.creditStrategy);
+    this.playbookExtractor = createPlaybookExtractor({
+      minTrajectories: this.learningConfig.minTrajectories,
+      mergeThreshold: this.learningConfig.deduplicationThreshold,
+      minSuccessRate: this.learningConfig.minSuccessRate ?? 0.6,
+    });
+
+    this.knowledgeExtractor = (this.config.features.knowledgeExtraction ?? true)
+      ? new KnowledgeExtractor()
+      : null;
+
+    this.temporalCompressor = (this.config.features.temporalCompression ?? true)
+      ? new TemporalCompressor(undefined, persistence)
+      : null;
+
+    this.reasoningBank = (this.config.features.reasoningBank ?? true)
+      ? new ReasoningBank(undefined, persistence)
+      : null;
+
+    // Orchestration
+    this.energyEvaluator = new EnergyEvaluator({
+      countThreshold: this.learningConfig.minTrajectories,
+      ...this.config.batch.energy,
+    });
+
+    this.maintenanceScheduler = new MaintenanceScheduler(this.config.maintenance);
+    this.healingOrchestrator = new HealingOrchestrator();
+
+    // Register built-in healing detectors if healing feature is enabled
+    if (this.config.features.healing ?? true) {
+      this.healingOrchestrator.addDetector(new PlaybookDriftDetector());
+      this.healingOrchestrator.addDetector(
+        new MemoryBloatDetector(this.learningConfig.maxExperiences),
+      );
+    }
+
+    // Register built-in maintenance tasks
+    this.registerBuiltInMaintenanceTasks();
+  }
+
+  /**
+   * Load persisted state for internal components.
+   * Call after persistence is initialized.
+   */
+  loadPersistedState(): void {
+    this.temporalCompressor?.loadPersistedState();
+    this.reasoningBank?.loadPersistedState();
+  }
+
+  /**
+   * Initialize components that require async setup.
+   */
+  async init(): Promise<void> {
+    // Seed known domains from existing playbooks for energy evaluator
+    const allPlaybooks = await this.memory.playbooks.getAll();
+    const domains = new Set<string>();
+    for (const pb of allPlaybooks) {
+      for (const d of pb.applicability.domains) {
+        domains.add(d);
+      }
+    }
+    this.energyEvaluator.seedKnownDomains([...domains]);
+
+    // Initialize meta-learner if enabled and meta memory available
+    if ((this.config.features.metaLearning ?? true) && this.memory.meta) {
+      const { createMetaLearner: createML } = await import('./meta-learner.js');
+      this.metaLearner = createML(this.memory.meta, this.config.metaLearner);
+    }
+
+    // Initialize effectiveness tracker if enabled
+    if (this.config.features.effectivenessTracking ?? true) {
+      // Effectiveness tracker is available through memory system
+      this.effectivenessTracker = this.memory.effectiveness;
+      await this.effectivenessTracker.init();
+    }
+  }
+
+  /**
+   * Set the agentic task runner for workspace-based analysis.
+   */
+  setTaskRunner(runner: AgenticTaskRunner): void {
+    this.taskRunner = runner;
+  }
+
+  // =========================================================================
+  // IMMEDIATE PHASE
+  // =========================================================================
+
+  /**
+   * Process a single trajectory through the full pipeline.
+   *
+   * 1. Runs the instant loop (immediate phase)
+   * 2. Evaluates energy to decide on batch trigger
+   * 3. If batch triggered, runs batch + checks maintenance
+   *
+   * This is the primary entry point for trajectory processing.
+   */
+  async processTrajectory(
+    trajectory: Trajectory,
+    signals?: Partial<EnergySignal>,
+  ): Promise<ImmediateResult> {
+    // 1. Immediate phase — InstantLoop
+    const instantResult = await this.instantLoop.process(trajectory);
+    this.totalProcessed++;
+
+    // Warn if instant loop exceeded latency budget
+    if (instantResult.durationMs > this.config.maxInstantLatencyMs) {
+      this._onLatencyWarning?.(instantResult.durationMs);
+    }
+
+    // 2. Accumulate for batch
+    let analysis: AnalysisResult;
+    if (this.taskRunner) {
+      analysis = await this.analyzeWithTemplate(trajectory);
+    } else {
+      analysis = await this.analyzer.analyze(trajectory);
+    }
+    this.accumulated.push(trajectory);
+    this.accumulatedAnalyses.push(analysis);
+
+    // 3. Energy evaluation
+    const energyEval = this.energyEvaluator.evaluate(
+      trajectory,
+      instantResult,
+      signals,
+    );
+
+    const result: ImmediateResult = {
+      instantLoop: instantResult,
+      energyEval,
+      batchTriggered: false,
+      maintenanceTriggered: false,
+    };
+
+    // 4. Batch trigger
+    if (energyEval.shouldTriggerBatch) {
+      const batchResult = await this.runBatch(energyEval.reasons);
+      result.batchTriggered = true;
+      result.batchResult = batchResult;
+
+      // 5. Check maintenance after batch
+      this.maintenanceScheduler.onBatchComplete();
+      if (this.maintenanceScheduler.shouldRunMaintenance()) {
+        const maintenanceResult = await this.runMaintenance();
+        result.maintenanceTriggered = true;
+        result.maintenanceResult = maintenanceResult;
+      }
+    }
+
+    return result;
+  }
+
+  // =========================================================================
+  // BATCH PHASE
+  // =========================================================================
+
+  /**
+   * Run batch learning on accumulated trajectories.
+   * Can be called manually or triggered by energy evaluation.
+   */
+  async runBatch(triggerReasons?: EscalationReason[]): Promise<UnifiedBatchResult> {
+    if (this.accumulated.length === 0) {
+      return this.emptyBatchResult(triggerReasons ?? []);
+    }
+
+    this.maintenanceScheduler.onBatchStart();
+
+    try {
+      // Extract playbooks
+      let playbooksAdded = 0;
+      const existingPlaybooks = await this.memory.playbooks.getAll();
+      const playbookExtraction = await this.extractPlaybooks(existingPlaybooks);
+
+      for (const playbook of playbookExtraction.new) {
+        const exists = await this.memory.playbooks.exists(
+          playbook.name,
+          this.learningConfig.deduplicationThreshold,
+        );
+        if (!exists) {
+          await this.memory.playbooks.add(playbook);
+          playbooksAdded++;
+        }
+      }
+
+      // Apply updates to existing playbooks
+      for (const update of playbookExtraction.updates) {
+        if (update.refinement) {
+          await this.memory.playbooks.addRefinement(
+            update.id,
+            update.refinement.context,
+            update.refinement.addition,
+            update.refinement.source,
+          );
+        }
+        if (update.newTrigger) {
+          const playbook = await this.memory.playbooks.get(update.id);
+          if (playbook && !playbook.applicability.triggers.includes(update.newTrigger)) {
+            playbook.applicability.triggers.push(update.newTrigger);
+            await this.memory.playbooks.add(playbook);
+          }
+        }
+        if (update.newAntiPattern) {
+          const playbook = await this.memory.playbooks.get(update.id);
+          if (playbook && !playbook.applicability.antiPatterns.includes(update.newAntiPattern)) {
+            playbook.applicability.antiPatterns.push(update.newAntiPattern);
+            await this.memory.playbooks.add(playbook);
+          }
+        }
+      }
+
+      // Knowledge extraction (batch-level, richer than instant-loop)
+      let knowledgeExtracted = 0;
+      if (this.knowledgeExtractor && this.memory.knowledgeBank) {
+        const existingEntities = await this.memory.knowledgeBank.listEntities();
+        const context: ExtractionContext = { existingEntities };
+
+        for (let i = 0; i < this.accumulated.length; i++) {
+          const extracted = this.knowledgeExtractor.extract(
+            this.accumulated[i],
+            this.accumulatedAnalyses[i],
+            context,
+          );
+          for (const obs of extracted.observations) {
+            try {
+              await this.memory.knowledgeBank.addObservation(obs);
+              knowledgeExtracted++;
+            } catch {
+              // Non-critical
+            }
+          }
+        }
+      }
+
+      // Temporal compression
+      let compressionEvicted = 0;
+      let compressionPromoted = 0;
+      let compressionDemoted = 0;
+
+      if (this.temporalCompressor) {
+        const allExperiences = await this.memory.experiences.getAll();
+        const compressionResult = await this.temporalCompressor.compress(allExperiences);
+
+        for (const [id, updates] of compressionResult.updates) {
+          await this.memory.experiences.update(id, updates);
+        }
+        for (const id of compressionResult.evicted) {
+          await this.memory.experiences.delete(id);
+        }
+
+        compressionEvicted = compressionResult.evicted.length;
+        compressionPromoted = compressionResult.promoted.length;
+        compressionDemoted = compressionResult.demoted.length;
+      }
+
+      // Re-cluster experiences
+      const currentExperiences = await this.memory.experiences.getAll();
+      if (this.reasoningBank) {
+        this.reasoningBank.buildClusters(currentExperiences);
+      }
+
+      // Prune experiences
+      const pruned = await this.memory.experiences.prune({
+        maxCount: this.learningConfig.maxExperiences,
+      });
+
+      // Calculate success rate
+      const successCount = this.accumulatedAnalyses.filter(a => a.success).length;
+      const successRate = successCount / this.accumulated.length;
+
+      // Meta-learning: generate strategies periodically
+      if (this.metaLearner) {
+        try {
+          await this.metaLearner.learn();
+        } catch {
+          // Non-critical
+        }
+      }
+
+      const trajectoriesProcessed = this.accumulated.length;
+
+      // Clear accumulated and reset energy evaluator
+      this.accumulated = [];
+      this.accumulatedAnalyses = [];
+      this.energyEvaluator.resetAfterBatch();
+      this.batchCyclesRun++;
+
+      return {
+        trajectoriesProcessed,
+        playbooksExtracted: playbooksAdded,
+        experiencesPruned: pruned.totalPruned + compressionEvicted,
+        experiencesCompressed: {
+          promoted: compressionPromoted,
+          demoted: compressionDemoted,
+          evicted: compressionEvicted,
+        },
+        experiencesClustered: currentExperiences.length,
+        knowledgeExtracted,
+        successRate,
+        triggerReasons: triggerReasons ?? ['manual_override'],
+      };
+    } finally {
+      this.maintenanceScheduler.onBatchEnd();
+    }
+  }
+
+  // =========================================================================
+  // MAINTENANCE PHASE
+  // =========================================================================
+
+  /**
+   * Run a maintenance cycle.
+   * Executes registered maintenance tasks (defrag, healing, etc.).
+   * Can be called manually regardless of mode.
+   */
+  async runMaintenance(options?: { force?: boolean }): Promise<MaintenanceCycleResult> {
+    const result = await this.maintenanceScheduler.runMaintenance(options);
+    if (result.ran) {
+      this.maintenanceCyclesRun++;
+    }
+    return result;
+  }
+
+  /**
+   * Register a custom maintenance task.
+   */
+  registerMaintenanceTask(task: MaintenanceTask): void {
+    this.maintenanceScheduler.registerTask(task);
+  }
+
+  /**
+   * Register a custom anomaly detector for the healing orchestrator.
+   */
+  addAnomalyDetector(detector: AnomalyDetector): void {
+    this.healingOrchestrator.addDetector(detector);
+  }
+
+  /**
+   * Register a custom repair strategy for the healing orchestrator.
+   */
+  addRepairStrategy(strategy: RepairStrategy): void {
+    this.healingOrchestrator.addRepairStrategy(strategy);
+  }
+
+  // =========================================================================
+  // ACCESSORS
+  // =========================================================================
+
+  /**
+   * Get the meta-learner instance.
+   */
+  getMetaLearner(): MetaLearner | null {
+    return this.metaLearner;
+  }
+
+  /**
+   * Get the effectiveness tracker.
+   */
+  getEffectivenessTracker(): LearningEffectivenessTracker | null {
+    return this.effectivenessTracker;
+  }
+
+  /**
+   * Get the energy evaluator.
+   */
+  getEnergyEvaluator(): EnergyEvaluator {
+    return this.energyEvaluator;
+  }
+
+  /**
+   * Get the maintenance scheduler.
+   */
+  getMaintenanceScheduler(): MaintenanceScheduler {
+    return this.maintenanceScheduler;
+  }
+
+  /**
+   * Get the healing orchestrator.
+   */
+  getHealingOrchestrator(): HealingOrchestrator {
+    return this.healingOrchestrator;
+  }
+
+  /**
+   * Get accumulated trajectory count.
+   */
+  getAccumulatedCount(): number {
+    return this.accumulated.length;
+  }
+
+  /**
+   * Get accumulated trajectories with analyses (read-only).
+   */
+  getAccumulated(): TrajectoryWithAnalysis[] {
+    return this.accumulated.map((trajectory, i) => ({
+      trajectory,
+      analysis: this.accumulatedAnalyses[i],
+    }));
+  }
+
+  /**
+   * Get pipeline statistics.
+   */
+  getStats(): UnifiedPipelineStats {
+    return {
+      totalProcessed: this.totalProcessed,
+      batchCyclesRun: this.batchCyclesRun,
+      maintenanceCyclesRun: this.maintenanceCyclesRun,
+      pendingForBatch: this.energyEvaluator.getPendingCount(),
+      batchesSinceLastMaintenance: this.maintenanceScheduler.getBatchesSinceLastMaintenance(),
+      maintenanceTasks: this.maintenanceScheduler.getRegisteredTasks().map(t => t.name),
+      anomalyDetectors: this.healingOrchestrator.getDetectors().map(d => d.name),
+      repairStrategies: this.healingOrchestrator.getRepairStrategies().map(s => s.name),
+    };
+  }
+
+  /**
+   * Register a callback for instant-loop latency warnings.
+   */
+  onLatencyWarning(callback: (durationMs: number) => void): void {
+    this._onLatencyWarning = callback;
+  }
+
+  /**
+   * Update batch learning configuration.
+   */
+  updateConfig(config: Partial<LearningConfig>): void {
+    this.learningConfig = { ...this.learningConfig, ...config };
+    if (config.creditStrategy) {
+      this.analyzer.setStrategy(config.creditStrategy);
+    }
+  }
+
+  // =========================================================================
+  // PRIVATE
+  // =========================================================================
+
+  /**
+   * Register built-in maintenance tasks.
+   */
+  private registerBuiltInMaintenanceTasks(): void {
+    // Healing cycle
+    this.maintenanceScheduler.registerTask({
+      name: 'healing-cycle',
+      priority: 100,
+      execute: async () => {
+        const start = Date.now();
+        const context = await this.buildHealthContext();
+        const result = await this.healingOrchestrator.runCycle(context);
+        return {
+          taskName: 'healing-cycle',
+          success: true,
+          durationMs: Date.now() - start,
+          details: {
+            anomaliesDetected: result.anomaliesDetected.length,
+            repairsAttempted: result.repairs.length,
+            repairsSucceeded: result.repairs.filter(r => r.success).length,
+          },
+        };
+      },
+    });
+
+    // Knowledge defrag (if knowledge bank is available)
+    if (this.memory.knowledgeBank) {
+      this.maintenanceScheduler.registerTask({
+        name: 'knowledge-defrag',
+        priority: 80,
+        execute: async () => {
+          const start = Date.now();
+          const kb = this.memory.knowledgeBank!;
+          const shouldDefrag = await kb.shouldDefragment();
+          if (!shouldDefrag) {
+            return {
+              taskName: 'knowledge-defrag',
+              success: true,
+              durationMs: Date.now() - start,
+              details: { skipped: true, reason: 'not needed' },
+            };
+          }
+          const result = await kb.defragment();
+          return {
+            taskName: 'knowledge-defrag',
+            success: true,
+            durationMs: Date.now() - start,
+            details: result as unknown as Record<string, unknown>,
+          };
+        },
+      });
+    }
+
+    // Meta-strategy generation
+    if (this.config.features.metaLearning ?? true) {
+      this.maintenanceScheduler.registerTask({
+        name: 'meta-strategy-generation',
+        priority: 60,
+        execute: async () => {
+          const start = Date.now();
+          if (!this.metaLearner) {
+            return {
+              taskName: 'meta-strategy-generation',
+              success: true,
+              durationMs: Date.now() - start,
+              details: { skipped: true, reason: 'meta-learner not initialized' },
+            };
+          }
+          const strategies = await this.metaLearner.learn();
+          return {
+            taskName: 'meta-strategy-generation',
+            success: true,
+            durationMs: Date.now() - start,
+            details: { strategiesGenerated: strategies.length },
+          };
+        },
+      });
+    }
+  }
+
+  /**
+   * Build health context for the healing orchestrator.
+   */
+  private async buildHealthContext(): Promise<HealthContext> {
+    const [experienceCount, playbookCount] = await Promise.all([
+      this.memory.experiences.count(),
+      this.memory.playbooks.count(),
+    ]);
+
+    // Compute recent success rate from accumulated analyses
+    const recentAnalyses = this.accumulatedAnalyses.length > 0
+      ? this.accumulatedAnalyses
+      : [];
+    const recentSuccessRate = recentAnalyses.length > 0
+      ? recentAnalyses.filter(a => a.success).length / recentAnalyses.length
+      : 1.0;
+
+    return {
+      trajectoriesProcessed: this.totalProcessed,
+      experienceCount,
+      playbookCount,
+      recentSuccessRate,
+      batchesSinceLastMaintenance: this.maintenanceScheduler.getBatchesSinceLastMaintenance(),
+      metrics: {},
+    };
+  }
+
+  /**
+   * Analyze a trajectory via workspace template or heuristic fallback.
+   */
+  private async analyzeWithTemplate(trajectory: Trajectory): Promise<AnalysisResult> {
+    try {
+      const result = await this.taskRunner!.run(trajectoryAnalysisTemplate, {
+        trajectory,
+        creditStrategy: this.learningConfig.creditStrategy,
+      });
+      return result.output;
+    } catch {
+      return this.analyzer.analyze(trajectory);
+    }
+  }
+
+  /**
+   * Extract playbooks via workspace template or heuristic fallback.
+   */
+  private async extractPlaybooks(
+    existingPlaybooks: Playbook[],
+  ): ReturnType<PlaybookExtractor['extract']> {
+    if (this.taskRunner) {
+      try {
+        const result = await this.taskRunner.run(playbookExtractionTemplate, {
+          trajectories: this.accumulated,
+          analyses: this.accumulatedAnalyses,
+          existingPlaybooks,
+        });
+        return result.output;
+      } catch {
+        // Fall through to heuristic
+      }
+    }
+
+    return this.playbookExtractor.extract(
+      this.accumulated,
+      this.accumulatedAnalyses,
+      existingPlaybooks,
+    );
+  }
+
+  /**
+   * Empty batch result for when there's nothing to process.
+   */
+  private emptyBatchResult(triggerReasons: EscalationReason[]): UnifiedBatchResult {
+    return {
+      trajectoriesProcessed: 0,
+      playbooksExtracted: 0,
+      experiencesPruned: 0,
+      experiencesCompressed: { promoted: 0, demoted: 0, evicted: 0 },
+      experiencesClustered: 0,
+      knowledgeExtracted: 0,
+      successRate: 0,
+      triggerReasons,
+    };
+  }
+}
+
+/**
+ * Create a UnifiedLearningPipeline.
+ */
+export function createUnifiedPipeline(
+  memory: MemorySystem,
+  config?: Partial<UnifiedPipelineConfig>,
+  persistence?: SqlitePersistence,
+): UnifiedLearningPipeline {
+  return new UnifiedLearningPipeline(memory, config, persistence);
+}