agentic-qe 3.8.11 → 3.8.12

package/dist/integrations/ruvector/domain-transfer.js

@@ -3,7 +3,8 @@
  *
  * Enables knowledge transfer between QE domains using Thompson Sampling
  * with Beta priors, sqrt-dampening, transfer verification gates, domain
- * pair affinity scoring, and coherence gate integration.
+ * pair affinity scoring, coherence gate integration, and R7 meta-learning
+ * enhancements (DecayingBeta, PlateauDetector, ParetoFront, CuriosityBonus).
  *
  * @module integrations/ruvector/domain-transfer
  */
@@ -12,6 +13,7 @@ import { createTransferCoherenceGate } from './transfer-coherence-stub.js';
 import { createTransferVerifier, } from './transfer-verification.js';
 import { getRuVectorFeatureFlags } from './feature-flags.js';
 import { ThompsonSampler } from './thompson-sampler.js';
+import { CusumDetector } from './cusum-detector.js';
 export { ThompsonSampler } from './thompson-sampler.js';
 const logger = LoggerFactory.create('domain-transfer');
 /** Default domain transfer configuration */
@@ -20,7 +22,115 @@ export const DEFAULT_DOMAIN_TRANSFER_CONFIG = {
     explorationWarmup: 5,
     verification: {},
     maxHistorySize: 1000,
+    useMetaLearningEnhancements: true,
 };
+/** Applies time-based decay to Thompson Sampler exploration variance. */
+export class DecayingBeta {
+    decayThreshold;
+    constructor(decayThreshold = 100) {
+        this.decayThreshold = decayThreshold;
+    }
+    /** Decay multiplier: 0.5^(successCount/threshold). 1.0 when count=0, 0.5 at threshold. */
+    getDecayMultiplier(successCount) {
+        if (successCount <= 0)
+            return 1.0;
+        return Math.pow(0.5, successCount / this.decayThreshold);
+    }
+    /** Shrink sampled value toward mean by the decay multiplier. */
+    applyDecay(sampled, mean, successCount) {
+        return mean + (sampled - mean) * this.getDecayMultiplier(successCount);
+    }
+}
+/**
+ * Detects when transfer success rate has plateaued using CUSUM (R2).
+ *
+ * Feeds a running success rate into a CusumDetector on the 'learn' gate.
+ * Plateau is detected when CUSUM does NOT fire — i.e., the rate is
+ * stationary (no drift in either direction) for enough samples.
+ * CUSUM firing means the rate is changing, so NOT plateaued.
+ */
+export class PlateauDetector {
+    cusum;
+    outcomes = [];
+    windowSize;
+    constructor(windowSize = 20) {
+        this.windowSize = windowSize;
+        // Low threshold + low slack = sensitive to any drift from mean.
+        // If CUSUM doesn't fire after windowSize samples, rate is flat.
+        // resetOnAlarm: false keeps the drift flag active so isPlateaued()
+        // returns false for the rest of the window after a rate change.
+        this.cusum = new CusumDetector({
+            threshold: 3.0,
+            slack: 0.1,
+            resetOnAlarm: false,
+            warmupSamples: Math.min(10, Math.floor(windowSize / 2)),
+        });
+    }
+    record(success) {
+        this.outcomes.push(success);
+        if (this.outcomes.length > this.windowSize * 2) {
+            this.outcomes.splice(0, this.outcomes.length - this.windowSize * 2);
+        }
+        // Feed current success rate to CUSUM on the 'learn' gate
+        const rate = this.getCurrentRate();
+        this.cusum.update('learn', rate);
+    }
+    /**
+     * Plateau = we have enough data AND CUSUM has not detected drift.
+     * No drift means the rate is stationary — learning has stalled.
+     */
+    isPlateaued() {
+        if (this.outcomes.length < this.windowSize)
+            return false;
+        const state = this.cusum.getState('learn');
+        return !state.driftDetected;
+    }
+    getCurrentRate() {
+        if (this.outcomes.length === 0)
+            return 0;
+        const recent = this.outcomes.slice(-this.windowSize);
+        return recent.filter(Boolean).length / recent.length;
+    }
+    getOutcomeCount() { return this.outcomes.length; }
+    /** Expose CUSUM state for observability */
+    getCusumState() { return this.cusum.getState('learn'); }
+}
+/** Tracks Pareto-optimal transfer candidates across multiple objectives. */
+export class ParetoFront {
+    front = [];
+    dominates(a, b) {
+        const geq = a.successRate >= b.successRate && a.speed >= b.speed && a.confidence >= b.confidence;
+        const gt = a.successRate > b.successRate || a.speed > b.speed || a.confidence > b.confidence;
+        return geq && gt;
+    }
+    add(point) {
+        for (let i = this.front.length - 1; i >= 0; i--) {
+            if (this.dominates(point, this.front[i]))
+                this.front.splice(i, 1);
+        }
+        if (!this.front.some(e => this.dominates(e, point)))
+            this.front.push(point);
+    }
+    getFront() { return [...this.front]; }
+    isNonDominated(point) {
+        return !this.front.some(e => this.dominates(e, point));
+    }
+}
+/** Curiosity bonus for novel/untried source-target domain pairs. */
+export class CuriosityBonus {
+    bonusScale;
+    triedPairs = new Set();
+    constructor(bonusScale = 0.2) {
+        this.bonusScale = bonusScale;
+    }
+    markTried(pairKey) { this.triedPairs.add(pairKey); }
+    isTried(pairKey) { return this.triedPairs.has(pairKey); }
+    getBonus(pairKey) { return this.triedPairs.has(pairKey) ? 0 : this.bonusScale; }
+    apply(sampledProbability, pairKey) {
+        return Math.min(1.0, sampledProbability + this.getBonus(pairKey));
+    }
+    getTriedCount() { return this.triedPairs.size; }
+}
 // ============================================================================
 // Domain Transfer Engine
 // ============================================================================
@@ -38,26 +148,44 @@ export class DomainTransferEngine {
     performanceProvider = null;
     transferExecutor = null;
     nativeModule = null;
+    // R7 Meta-Learning components (ADR-087, Milestone 3)
+    decayingBeta;
+    plateauDetector;
+    paretoFront;
+    curiosityBonus;
     constructor(config = {}) {
         this.config = { ...DEFAULT_DOMAIN_TRANSFER_CONFIG, ...config };
         this.sampler = new ThompsonSampler();
         this.verifier = createTransferVerifier(this.config.verification);
         this.coherenceGate = createTransferCoherenceGate();
+        this.decayingBeta = new DecayingBeta();
+        this.plateauDetector = new PlateauDetector();
+        this.paretoFront = new ParetoFront();
+        this.curiosityBonus = new CuriosityBonus();
         this.tryLoadNativeModule();
     }
     /**
      * Evaluate whether a transfer between two domains should be attempted.
      * Uses Thompson Sampling to balance exploration and exploitation.
+     * When meta-learning is enabled, applies DecayingBeta and CuriosityBonus.
      */
     evaluateTransfer(sourceDomain, targetDomain) {
         if (!this.isEnabled()) {
             return this.createRejectedCandidate(sourceDomain, targetDomain);
         }
         const pairKey = this.makePairKey(sourceDomain, targetDomain);
-        const sampledProbability = this.sampler.sample(pairKey);
+        let sampledProbability = this.sampler.sample(pairKey);
         const observationCount = this.sampler.getObservationCount(pairKey);
         const isExploration = observationCount < this.config.explorationWarmup;
         const affinityScore = this.getAffinityScore(sourceDomain, targetDomain);
+        if (this.isMetaLearningEnabled()) {
+            // DecayingBeta: reduce exploration variance for well-known pairs
+            const mean = this.sampler.getMean(pairKey);
+            const successCount = this.sampler.getAlpha(pairKey) - 1; // subtract prior
+            sampledProbability = this.decayingBeta.applyDecay(sampledProbability, mean, successCount);
+            // CuriosityBonus: boost untried domain pairs
+            sampledProbability = this.curiosityBonus.apply(sampledProbability, pairKey);
+        }
         return { sourceDomain, targetDomain, sampledProbability, affinityScore, isExploration, pairKey };
     }
     /**
@@ -93,6 +221,18 @@ export class DomainTransferEngine {
         // Step 6: Update Thompson Sampling and affinity
         this.sampler.update(candidate.pairKey, success);
         this.updateAffinityScore(candidate.pairKey, success);
+        // Step 6b: Update meta-learning components
+        if (this.isMetaLearningEnabled()) {
+            this.plateauDetector.record(success);
+            this.curiosityBonus.markTried(candidate.pairKey);
+            const mean = this.sampler.getMean(candidate.pairKey);
+            this.paretoFront.add({
+                pairKey: candidate.pairKey,
+                successRate: mean,
+                speed: 1 / (1 + dampeningFactor), // inverse dampening as speed proxy
+                confidence: this.getAffinityScore(candidate.sourceDomain, candidate.targetDomain),
+            });
+        }
         this.addToHistory({
             transferId, sourceDomain: candidate.sourceDomain, targetDomain: candidate.targetDomain,
             success, sampledProbability: candidate.sampledProbability, dampeningFactor,
@@ -140,10 +280,26 @@ export class DomainTransferEngine {
     getSampler() { return this.sampler; }
     /** Get the coherence gate (for testing). */
     getCoherenceGate() { return this.coherenceGate; }
+    /** Get the DecayingBeta component (for testing). */
+    getDecayingBeta() { return this.decayingBeta; }
+    /** Get the PlateauDetector component (for testing). */
+    getPlateauDetector() { return this.plateauDetector; }
+    /** Get the ParetoFront component (for testing). */
+    getParetoFront() { return this.paretoFront; }
+    /** Get the CuriosityBonus component (for testing). */
+    getCuriosityBonus() { return this.curiosityBonus; }
+    /** Check if learning has plateaued */
+    isLearningPlateaued() { return this.plateauDetector.isPlateaued(); }
     // --- Private Helpers ---
     isEnabled() {
         return getRuVectorFeatureFlags().useCrossDomainTransfer === true;
     }
+    isMetaLearningEnabled() {
+        // Check both the engine config AND the system-wide feature flag.
+        // Either one being false disables meta-learning.
+        return this.config.useMetaLearningEnhancements === true
+            && getRuVectorFeatureFlags().useMetaLearningEnhancements !== false;
+    }
     makePairKey(source, target) {
         return `${source}->${target}`;
     }

package/dist/integrations/ruvector/eprop-learner.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Agentic QE v3 - E-prop Online Learning (ADR-087 Milestone 4, R11)
+ *
+ * Eligibility propagation for online learning with 12 bytes/synapse,
+ * no backprop required. Uses eligibility traces and feedback alignment
+ * (Lillicrap et al. 2016) to avoid the weight transport problem.
+ *
+ * Algorithm: dw = eta * eligibility * reward
+ * Memory budget: 4B weight + 4B trace + 4B feedback = 12 bytes/synapse
+ */
+export interface EpropConfig {
+    /** Number of input neurons */
+    inputSize: number;
+    /** Number of hidden neurons */
+    hiddenSize: number;
+    /** Number of output neurons */
+    outputSize: number;
+    /** Learning rate (eta) */
+    learningRate: number;
+    /** Eligibility trace decay factor (tau_e) */
+    eligibilityDecay: number;
+    /** Use random feedback weights instead of weight transport */
+    feedbackAlignment: boolean;
+}
+export interface EpropStats {
+    totalSteps: number;
+    totalReward: number;
+    avgReward: number;
+    synapsCount: number;
+    memoryBytes: number;
+}
+/**
+ * E-prop neural network with online eligibility-trace learning.
+ *
+ * Architecture: input -> hidden (tanh) -> output (softmax or linear)
+ *
+ * Each synapse stores exactly 12 bytes:
+ *   - weight:    Float32 (4 bytes)
+ *   - trace:     Float32 (4 bytes)  — eligibility trace
+ *   - feedback:  Float32 (4 bytes)  — random feedback weight (fixed)
+ */
+export declare class EpropNetwork {
+    private readonly config;
+    private inputHiddenWeights;
+    private hiddenOutputWeights;
+    private inputHiddenTraces;
+    private hiddenOutputTraces;
+    private feedbackWeights;
+    private lastInput;
+    private lastHidden;
+    private lastHiddenRaw;
+    private lastOutput;
+    private totalSteps;
+    private totalReward;
+    private rewardHistory;
+    constructor(config?: Partial<EpropConfig>);
+    /**
+     * Compute output from input. Stores activations for eligibility updates.
+     *
+     * input -> (inputHidden weights) -> tanh -> (hiddenOutput weights) -> output
+     *
+     * Output activation depends on outputSize:
+     *   - outputSize === 1: sigmoid (for binary tasks)
+     *   - outputSize > 1:  softmax (for classification)
+     */
+    forward(input: Float32Array): Float32Array;
+    /**
+     * Update weights using eligibility traces and reward/error signal.
+     *
+     * Hidden->output layer:
+     *   dw[j][k] = learningRate * e_ho[j][k] * reward
+     *
+     * Input->hidden layer (feedback alignment):
+     *   The learning signal for hidden neuron j is computed by projecting
+     *   the scalar reward through feedback weights (or transposed output
+     *   weights if feedbackAlignment is false).
+     *   dw[i][j] = learningRate * e_ih[i][j] * L[j]
+     *   where L[j] = sum_k(B[k][j] * reward)  [feedback alignment]
+     *         L[j] = sum_k(W_ho[j][k] * reward) [weight transport]
+     */
+    updateOnline(reward: number): void;
+    /**
+     * Update eligibility traces after a forward pass.
+     *
+     * Traces capture purely local information (Hebbian-like):
+     *   Hidden->output: e[j][k] = decay * e[j][k] + h[j]
+     *   Input->hidden:  e[i][j] = decay * e[i][j] + x[i] * dtanh(raw[j])
+     *
+     * The feedback/learning signal is applied separately in updateOnline().
+     */
+    private updateTraces;
+    /**
+     * Reset all eligibility traces to zero (between episodes).
+     */
+    resetTraces(): void;
+    /**
+     * Get network statistics including memory budget verification.
+     */
+    getStats(): EpropStats;
+    /**
+     * Export current weights (without traces — those are transient).
+     */
+    exportWeights(): {
+        inputHidden: Float32Array;
+        hiddenOutput: Float32Array;
+    };
+    /**
+     * Import weights. Resets traces since the network state has changed.
+     */
+    importWeights(weights: {
+        inputHidden: Float32Array;
+        hiddenOutput: Float32Array;
+    }): void;
+    /** Get the current config (read-only). */
+    getConfig(): Readonly<EpropConfig>;
+    /** Get the raw eligibility trace values for testing/debugging. */
+    getTraces(): {
+        inputHidden: Float32Array;
+        hiddenOutput: Float32Array;
+    };
+    private validateConfig;
+    /** Xavier/Glorot uniform initialization */
+    private xavierInit;
+    /** Random uniform initialization in [-0.5, 0.5] */
+    private randomInit;
+    /** Sigmoid activation */
+    private sigmoid;
+    /** Softmax activation */
+    private softmax;
+}
+/**
+ * Create a new E-prop network with the given configuration.
+ */
+export declare function createEpropNetwork(config?: Partial<EpropConfig>): EpropNetwork;
+//# sourceMappingURL=eprop-learner.d.ts.map