cognitive-core 0.1.2 → 0.2.1

package/dist/learning/energy-evaluator.d.ts

@@ -0,0 +1,128 @@
+/**
+ * EnergyEvaluator — Ruvector-inspired energy-threshold batch trigger.
+ *
+ * Instead of a simple count threshold, the evaluator measures "incoherence
+ * energy" from trajectory signals. A trajectory that introduces contradictions,
+ * encounters a novel domain with no playbooks, or triggers a high error rate
+ * can escalate to batch processing even before the count threshold is met.
+ *
+ * Inspired by ruvector's Compute Ladder (prime-radiant/execution/ladder.rs)
+ * which uses energy-driven escalation with named transition reasons.
+ */
+import type { Trajectory } from '../types/index.js';
+import type { InstantLoopResult } from './instant-loop.js';
+/**
+ * Reasons why a batch was triggered — named transitions for audit.
+ */
+export type EscalationReason = 'count_threshold' | 'contradiction_detected' | 'novel_domain' | 'high_error_rate' | 'pattern_shift' | 'manual_override';
+/**
+ * Signals extracted from a trajectory that contribute to energy.
+ */
+export interface EnergySignal {
+    /** Whether a coherence contradiction was detected during instant loop */
+    contradictionDetected: boolean;
+    /** Whether this trajectory's domain has no existing playbooks */
+    novelDomain: boolean;
+    /** Error rate in the recent window exceeds threshold */
+    highErrorRate: boolean;
+    /** Significant shift in patterns (e.g., new tool usage, domain change) */
+    patternShift: boolean;
+}
+/**
+ * Result of an energy evaluation.
+ */
+export interface EnergyEvaluation {
+    /** Computed energy score (0.0 = calm, 1.0 = high incoherence) */
+    energy: number;
+    /** Whether the energy exceeds the batch trigger threshold */
+    shouldTriggerBatch: boolean;
+    /** Named reason(s) for the trigger decision */
+    reasons: EscalationReason[];
+}
+/**
+ * Lane transition record for audit purposes.
+ */
+export interface LaneTransition {
+    timestamp: Date;
+    fromPhase: 'immediate' | 'batch' | 'maintenance';
+    toPhase: 'immediate' | 'batch' | 'maintenance';
+    reasons: EscalationReason[];
+    energy: number;
+    trajectoryId: string;
+}
+/**
+ * Configuration for the EnergyEvaluator.
+ */
+export interface EnergyEvaluatorConfig {
+    /** Trajectories needed before count-based batch trigger (default: 10) */
+    countThreshold: number;
+    /** Trigger batch when a contradiction is detected (default: true) */
+    triggerOnContradiction: boolean;
+    /** Trigger batch when a novel domain is encountered (default: true) */
+    triggerOnNovelDomain: boolean;
+    /** Error rate threshold for triggering batch (default: 0.6) */
+    errorRateThreshold: number;
+    /** Minimum time between batches in ms — debounce (default: 30000) */
+    minIntervalMs: number;
+    /** Number of recent trajectories to consider for error rate (default: 5) */
+    recentWindowSize: number;
+    /** Energy threshold for triggering batch (0.0–1.0, default: 0.7) */
+    energyThreshold: number;
+    /** Energy contribution weights */
+    weights: {
+        contradiction: number;
+        novelDomain: number;
+        highErrorRate: number;
+        patternShift: number;
+    };
+}
+/**
+ * EnergyEvaluator — determines when batch processing should be triggered
+ * based on measured incoherence energy from trajectory signals.
+ */
+export declare class EnergyEvaluator {
+    private config;
+    private pendingCount;
+    private lastBatchTime;
+    private recentOutcomes;
+    private knownDomains;
+    private transitionLog;
+    constructor(config?: Partial<EnergyEvaluatorConfig>);
+    /**
+     * Record a trajectory and evaluate whether batch should be triggered.
+     */
+    evaluate(trajectory: Trajectory, _instantResult: InstantLoopResult, signals?: Partial<EnergySignal>): EnergyEvaluation;
+    /**
+     * Compute energy from signal using weighted sum.
+     */
+    private computeEnergy;
+    /**
+     * Reset after a batch run completes.
+     */
+    resetAfterBatch(): void;
+    /**
+     * Force-trigger evaluation (for manual override).
+     */
+    forceEvaluate(): EnergyEvaluation;
+    /**
+     * Seed known domains (e.g., from existing playbooks on init).
+     */
+    seedKnownDomains(domains: string[]): void;
+    /**
+     * Get the current pending count.
+     */
+    getPendingCount(): number;
+    /**
+     * Get the transition log for audit/debugging.
+     */
+    getTransitionLog(): readonly LaneTransition[];
+    /**
+     * Get current configuration.
+     */
+    getConfig(): Readonly<EnergyEvaluatorConfig>;
+}
+/**
+ * Create an EnergyEvaluator.
+ */
+export declare function createEnergyEvaluator(config?: Partial<EnergyEvaluatorConfig>): EnergyEvaluator;
+//# sourceMappingURL=energy-evaluator.d.ts.map

package/dist/learning/energy-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"energy-evaluator.d.ts","sourceRoot":"","sources":["../../src/learning/energy-evaluator.ts"],"names":[],"mappings":"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"}

package/dist/learning/energy-evaluator.js

@@ -0,0 +1,175 @@
+/**
+ * EnergyEvaluator — Ruvector-inspired energy-threshold batch trigger.
+ *
+ * Instead of a simple count threshold, the evaluator measures "incoherence
+ * energy" from trajectory signals. A trajectory that introduces contradictions,
+ * encounters a novel domain with no playbooks, or triggers a high error rate
+ * can escalate to batch processing even before the count threshold is met.
+ *
+ * Inspired by ruvector's Compute Ladder (prime-radiant/execution/ladder.rs)
+ * which uses energy-driven escalation with named transition reasons.
+ */
+const DEFAULT_CONFIG = {
+    countThreshold: 10,
+    triggerOnContradiction: true,
+    triggerOnNovelDomain: true,
+    errorRateThreshold: 0.6,
+    minIntervalMs: 30_000,
+    recentWindowSize: 5,
+    energyThreshold: 0.7,
+    weights: {
+        contradiction: 0.4,
+        novelDomain: 0.3,
+        highErrorRate: 0.2,
+        patternShift: 0.1,
+    },
+};
+/**
+ * EnergyEvaluator — determines when batch processing should be triggered
+ * based on measured incoherence energy from trajectory signals.
+ */
+export class EnergyEvaluator {
+    config;
+    pendingCount = 0;
+    lastBatchTime = 0;
+    recentOutcomes = [];
+    knownDomains = new Set();
+    transitionLog = [];
+    constructor(config) {
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            weights: { ...DEFAULT_CONFIG.weights, ...config?.weights },
+        };
+    }
+    /**
+     * Record a trajectory and evaluate whether batch should be triggered.
+     */
+    evaluate(trajectory, _instantResult, signals) {
+        this.pendingCount++;
+        // Track recent outcomes for error rate
+        this.recentOutcomes.push(trajectory.outcome.success);
+        if (this.recentOutcomes.length > this.config.recentWindowSize) {
+            this.recentOutcomes.shift();
+        }
+        // Build the energy signal
+        const domain = trajectory.task.domain ?? 'general';
+        const isNovelDomain = !this.knownDomains.has(domain);
+        this.knownDomains.add(domain);
+        const errorRate = this.recentOutcomes.length > 0
+            ? this.recentOutcomes.filter(s => !s).length / this.recentOutcomes.length
+            : 0;
+        const signal = {
+            contradictionDetected: signals?.contradictionDetected ?? false,
+            novelDomain: isNovelDomain && (signals?.novelDomain ?? true),
+            highErrorRate: errorRate >= this.config.errorRateThreshold,
+            patternShift: signals?.patternShift ?? false,
+        };
+        // Compute energy
+        const energy = this.computeEnergy(signal);
+        // Determine reasons
+        const reasons = [];
+        if (this.pendingCount >= this.config.countThreshold) {
+            reasons.push('count_threshold');
+        }
+        if (signal.contradictionDetected && this.config.triggerOnContradiction) {
+            reasons.push('contradiction_detected');
+        }
+        if (signal.novelDomain && this.config.triggerOnNovelDomain) {
+            reasons.push('novel_domain');
+        }
+        if (signal.highErrorRate) {
+            reasons.push('high_error_rate');
+        }
+        if (signal.patternShift) {
+            reasons.push('pattern_shift');
+        }
+        // Check debounce
+        const now = Date.now();
+        const withinDebounce = (now - this.lastBatchTime) < this.config.minIntervalMs;
+        // Trigger if count threshold reached OR energy exceeds threshold
+        const shouldTrigger = !withinDebounce && (this.pendingCount >= this.config.countThreshold ||
+            energy >= this.config.energyThreshold);
+        if (shouldTrigger && reasons.length > 0) {
+            this.transitionLog.push({
+                timestamp: new Date(),
+                fromPhase: 'immediate',
+                toPhase: 'batch',
+                reasons,
+                energy,
+                trajectoryId: trajectory.id,
+            });
+        }
+        return {
+            energy,
+            shouldTriggerBatch: shouldTrigger,
+            reasons: shouldTrigger ? reasons : [],
+        };
+    }
+    /**
+     * Compute energy from signal using weighted sum.
+     */
+    computeEnergy(signal) {
+        const w = this.config.weights;
+        let energy = 0;
+        if (signal.contradictionDetected)
+            energy += w.contradiction;
+        if (signal.novelDomain)
+            energy += w.novelDomain;
+        if (signal.highErrorRate)
+            energy += w.highErrorRate;
+        if (signal.patternShift)
+            energy += w.patternShift;
+        return Math.min(1.0, energy);
+    }
+    /**
+     * Reset after a batch run completes.
+     */
+    resetAfterBatch() {
+        this.pendingCount = 0;
+        this.lastBatchTime = Date.now();
+    }
+    /**
+     * Force-trigger evaluation (for manual override).
+     */
+    forceEvaluate() {
+        return {
+            energy: 1.0,
+            shouldTriggerBatch: true,
+            reasons: ['manual_override'],
+        };
+    }
+    /**
+     * Seed known domains (e.g., from existing playbooks on init).
+     */
+    seedKnownDomains(domains) {
+        for (const d of domains) {
+            this.knownDomains.add(d);
+        }
+    }
+    /**
+     * Get the current pending count.
+     */
+    getPendingCount() {
+        return this.pendingCount;
+    }
+    /**
+     * Get the transition log for audit/debugging.
+     */
+    getTransitionLog() {
+        return this.transitionLog;
+    }
+    /**
+     * Get current configuration.
+     */
+    getConfig() {
+        return this.config;
+    }
+}
+/**
+ * Create an EnergyEvaluator.
+ */
+export function createEnergyEvaluator(config) {
+    return new EnergyEvaluator(config);
+}
+//# sourceMappingURL=energy-evaluator.js.map

package/dist/learning/energy-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"energy-evaluator.js","sourceRoot":"","sources":["../../src/learning/energy-evaluator.ts"],"names":[],"mappings":"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"}

package/dist/learning/healing-orchestrator.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 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 declare class HealingOrchestrator {
+    private detectors;
+    private strategies;
+    private cycleHistory;
+    private maxHistorySize;
+    constructor(options?: {
+        maxHistorySize?: number;
+    });
+    /**
+     * Register an anomaly detector.
+     */
+    addDetector(detector: AnomalyDetector): void;
+    /**
+     * Unregister an anomaly detector by name.
+     */
+    removeDetector(name: string): void;
+    /**
+     * Register a repair strategy.
+     */
+    addRepairStrategy(strategy: RepairStrategy): void;
+    /**
+     * Unregister a repair strategy by name.
+     */
+    removeRepairStrategy(name: string): void;
+    /**
+     * 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
+     */
+    runCycle(context: HealthContext): Promise<HealingCycleResult>;
+    /**
+     * Get cycle history for diagnostics.
+     */
+    getCycleHistory(): readonly HealingCycleResult[];
+    /**
+     * Get registered detectors.
+     */
+    getDetectors(): readonly AnomalyDetector[];
+    /**
+     * Get registered repair strategies.
+     */
+    getRepairStrategies(): readonly RepairStrategy[];
+}
+/**
+ * Create a HealingOrchestrator.
+ */
+export declare function createHealingOrchestrator(options?: {
+    maxHistorySize?: number;
+}): HealingOrchestrator;
+/**
+ * Detects when playbook success rates are consistently low,
+ * suggesting playbook drift.
+ */
+export declare class PlaybookDriftDetector implements AnomalyDetector {
+    readonly name = "playbook-drift";
+    private threshold;
+    constructor(threshold?: number);
+    detect(context: HealthContext): Promise<Anomaly[]>;
+}
+/**
+ * Detects when the experience store is growing beyond capacity,
+ * suggesting aggressive pruning is needed.
+ */
+export declare class MemoryBloatDetector implements AnomalyDetector {
+    readonly name = "memory-bloat";
+    private maxExperiences;
+    private warningRatio;
+    constructor(maxExperiences?: number, warningRatio?: number);
+    detect(context: HealthContext): Promise<Anomaly[]>;
+}
+/**
+ * Detects when a custom metric exceeds a Z-score threshold,
+ * inspired by ruvector's Z-score-based outlier detection.
+ */
+export declare class MetricDriftDetector implements AnomalyDetector {
+    readonly name: string;
+    private metricKey;
+    private history;
+    private windowSize;
+    private zThreshold;
+    constructor(metricKey: string, options?: {
+        windowSize?: number;
+        zThreshold?: number;
+    });
+    detect(context: HealthContext): Promise<Anomaly[]>;
+}
+//# sourceMappingURL=healing-orchestrator.d.ts.map

package/dist/learning/healing-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healing-orchestrator.d.ts","sourceRoot":"","sources":["../../src/learning/healing-orchestrator.ts"],"names":[],"mappings":"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"}