agentic-qe 3.8.11 → 3.8.13

package/dist/integrations/ruvector/eprop-learner.js

@@ -0,0 +1,351 @@
+/**
+ * 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
+ */
+import { secureRandom } from '../../shared/utils/crypto-random.js';
+const DEFAULT_EPROP_CONFIG = {
+    inputSize: 2,
+    hiddenSize: 16,
+    outputSize: 1,
+    learningRate: 0.01,
+    eligibilityDecay: 0.95,
+    feedbackAlignment: true,
+};
+// ============================================================================
+// E-prop Network
+// ============================================================================
+/**
+ * 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 class EpropNetwork {
+    config;
+    // Weights (Float32 = 4 bytes each)
+    inputHiddenWeights; // inputSize * hiddenSize
+    hiddenOutputWeights; // hiddenSize * outputSize
+    // Eligibility traces (Float32 = 4 bytes each)
+    inputHiddenTraces;
+    hiddenOutputTraces;
+    // Feedback alignment weights — fixed random, never updated (Float32 = 4 bytes each)
+    feedbackWeights; // outputSize * hiddenSize
+    // Activations (transient, not counted in memory budget)
+    lastInput;
+    lastHidden;
+    lastHiddenRaw; // pre-activation for derivative
+    lastOutput;
+    // Stats
+    totalSteps = 0;
+    totalReward = 0;
+    rewardHistory = [];
+    constructor(config) {
+        this.config = { ...DEFAULT_EPROP_CONFIG, ...config };
+        this.validateConfig(this.config);
+        const { inputSize, hiddenSize, outputSize } = this.config;
+        // Allocate weights with Xavier/Glorot initialization
+        this.inputHiddenWeights = this.xavierInit(inputSize, hiddenSize);
+        this.hiddenOutputWeights = this.xavierInit(hiddenSize, outputSize);
+        // Allocate traces (start at zero)
+        this.inputHiddenTraces = new Float32Array(inputSize * hiddenSize);
+        this.hiddenOutputTraces = new Float32Array(hiddenSize * outputSize);
+        // Allocate fixed random feedback weights
+        this.feedbackWeights = this.randomInit(outputSize, hiddenSize);
+        // Transient activations
+        this.lastInput = new Float32Array(inputSize);
+        this.lastHidden = new Float32Array(hiddenSize);
+        this.lastHiddenRaw = new Float32Array(hiddenSize);
+        this.lastOutput = new Float32Array(outputSize);
+    }
+    // ==========================================================================
+    // Forward Pass
+    // ==========================================================================
+    /**
+     * 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) {
+        const { inputSize, hiddenSize, outputSize } = this.config;
+        if (input.length !== inputSize) {
+            throw new Error(`Input size mismatch: expected ${inputSize}, got ${input.length}`);
+        }
+        // Store input for trace update
+        this.lastInput.set(input);
+        // Hidden layer: h = tanh(W_ih^T * x)
+        for (let j = 0; j < hiddenSize; j++) {
+            let sum = 0;
+            for (let i = 0; i < inputSize; i++) {
+                sum += input[i] * this.inputHiddenWeights[i * hiddenSize + j];
+            }
+            this.lastHiddenRaw[j] = sum;
+            this.lastHidden[j] = Math.tanh(sum);
+        }
+        // Output layer: o = W_ho^T * h (raw logits)
+        const rawOutput = new Float32Array(outputSize);
+        for (let k = 0; k < outputSize; k++) {
+            let sum = 0;
+            for (let j = 0; j < hiddenSize; j++) {
+                sum += this.lastHidden[j] * this.hiddenOutputWeights[j * outputSize + k];
+            }
+            rawOutput[k] = sum;
+        }
+        // Apply output activation
+        if (outputSize === 1) {
+            this.lastOutput[0] = this.sigmoid(rawOutput[0]);
+        }
+        else {
+            const softmaxResult = this.softmax(rawOutput);
+            this.lastOutput.set(softmaxResult);
+        }
+        // Update eligibility traces after forward pass
+        this.updateTraces();
+        this.totalSteps++;
+        return new Float32Array(this.lastOutput);
+    }
+    // ==========================================================================
+    // Online Learning
+    // ==========================================================================
+    /**
+     * 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) {
+        const { inputSize, hiddenSize, outputSize, learningRate, feedbackAlignment } = this.config;
+        // Update hidden->output weights: dw = eta * trace * reward
+        for (let j = 0; j < hiddenSize; j++) {
+            for (let k = 0; k < outputSize; k++) {
+                const idx = j * outputSize + k;
+                this.hiddenOutputWeights[idx] +=
+                    learningRate * this.hiddenOutputTraces[idx] * reward;
+            }
+        }
+        // Compute per-hidden-neuron learning signal via feedback alignment
+        const learningSignal = new Float32Array(hiddenSize);
+        if (feedbackAlignment) {
+            for (let j = 0; j < hiddenSize; j++) {
+                let signal = 0;
+                for (let k = 0; k < outputSize; k++) {
+                    signal += this.feedbackWeights[k * hiddenSize + j];
+                }
+                learningSignal[j] = signal * reward;
+            }
+        }
+        else {
+            // Weight transport: use transposed output weights
+            for (let j = 0; j < hiddenSize; j++) {
+                let signal = 0;
+                for (let k = 0; k < outputSize; k++) {
+                    signal += this.hiddenOutputWeights[j * outputSize + k];
+                }
+                learningSignal[j] = signal * reward;
+            }
+        }
+        // Update input->hidden weights: dw = eta * trace * learningSignal
+        for (let i = 0; i < inputSize; i++) {
+            for (let j = 0; j < hiddenSize; j++) {
+                const idx = i * hiddenSize + j;
+                this.inputHiddenWeights[idx] +=
+                    learningRate * this.inputHiddenTraces[idx] * learningSignal[j];
+            }
+        }
+        // Track reward
+        this.totalReward += reward;
+        this.rewardHistory.push(reward);
+        if (this.rewardHistory.length > 1000) {
+            this.rewardHistory.shift();
+        }
+    }
+    // ==========================================================================
+    // Trace Management
+    // ==========================================================================
+    /**
+     * 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().
+     */
+    updateTraces() {
+        const { inputSize, hiddenSize, outputSize, eligibilityDecay } = this.config;
+        // Hidden->output traces: e[j][k] = decay * e[j][k] + h[j]
+        for (let j = 0; j < hiddenSize; j++) {
+            for (let k = 0; k < outputSize; k++) {
+                const idx = j * outputSize + k;
+                this.hiddenOutputTraces[idx] =
+                    eligibilityDecay * this.hiddenOutputTraces[idx] + this.lastHidden[j];
+            }
+        }
+        // Input->hidden traces: e[i][j] = decay * e[i][j] + x[i] * dtanh(raw[j])
+        for (let i = 0; i < inputSize; i++) {
+            for (let j = 0; j < hiddenSize; j++) {
+                const idx = i * hiddenSize + j;
+                const tanhDerivative = 1 - this.lastHidden[j] * this.lastHidden[j];
+                this.inputHiddenTraces[idx] =
+                    eligibilityDecay * this.inputHiddenTraces[idx] +
+                        this.lastInput[i] * tanhDerivative;
+            }
+        }
+    }
+    /**
+     * Reset all eligibility traces to zero (between episodes).
+     */
+    resetTraces() {
+        this.inputHiddenTraces.fill(0);
+        this.hiddenOutputTraces.fill(0);
+    }
+    // ==========================================================================
+    // Statistics
+    // ==========================================================================
+    /**
+     * Get network statistics including memory budget verification.
+     */
+    getStats() {
+        const { inputSize, hiddenSize, outputSize } = this.config;
+        const synapseCount = inputSize * hiddenSize + // input->hidden
+            hiddenSize * outputSize; // hidden->output
+        return {
+            totalSteps: this.totalSteps,
+            totalReward: this.totalReward,
+            avgReward: this.rewardHistory.length > 0
+                ? this.rewardHistory.reduce((a, b) => a + b, 0) / this.rewardHistory.length
+                : 0,
+            synapsCount: synapseCount,
+            memoryBytes: synapseCount * 12, // 4B weight + 4B trace + 4B feedback
+        };
+    }
+    // ==========================================================================
+    // Weight Import / Export
+    // ==========================================================================
+    /**
+     * Export current weights (without traces — those are transient).
+     */
+    exportWeights() {
+        return {
+            inputHidden: new Float32Array(this.inputHiddenWeights),
+            hiddenOutput: new Float32Array(this.hiddenOutputWeights),
+        };
+    }
+    /**
+     * Import weights. Resets traces since the network state has changed.
+     */
+    importWeights(weights) {
+        const { inputSize, hiddenSize, outputSize } = this.config;
+        if (weights.inputHidden.length !== inputSize * hiddenSize) {
+            throw new Error(`inputHidden size mismatch: expected ${inputSize * hiddenSize}, got ${weights.inputHidden.length}`);
+        }
+        if (weights.hiddenOutput.length !== hiddenSize * outputSize) {
+            throw new Error(`hiddenOutput size mismatch: expected ${hiddenSize * outputSize}, got ${weights.hiddenOutput.length}`);
+        }
+        this.inputHiddenWeights.set(weights.inputHidden);
+        this.hiddenOutputWeights.set(weights.hiddenOutput);
+        this.resetTraces();
+    }
+    // ==========================================================================
+    // Internals
+    // ==========================================================================
+    /** Get the current config (read-only). */
+    getConfig() {
+        return { ...this.config };
+    }
+    /** Get the raw eligibility trace values for testing/debugging. */
+    getTraces() {
+        return {
+            inputHidden: new Float32Array(this.inputHiddenTraces),
+            hiddenOutput: new Float32Array(this.hiddenOutputTraces),
+        };
+    }
+    // ==========================================================================
+    // Private Helpers
+    // ==========================================================================
+    validateConfig(config) {
+        if (config.inputSize <= 0) {
+            throw new Error(`inputSize must be positive, got ${config.inputSize}`);
+        }
+        if (config.hiddenSize <= 0) {
+            throw new Error(`hiddenSize must be positive, got ${config.hiddenSize}`);
+        }
+        if (config.outputSize <= 0) {
+            throw new Error(`outputSize must be positive, got ${config.outputSize}`);
+        }
+        if (config.learningRate <= 0) {
+            throw new Error(`learningRate must be positive, got ${config.learningRate}`);
+        }
+        if (config.eligibilityDecay < 0 || config.eligibilityDecay > 1) {
+            throw new Error(`eligibilityDecay must be in [0, 1], got ${config.eligibilityDecay}`);
+        }
+    }
+    /** Xavier/Glorot uniform initialization */
+    xavierInit(fanIn, fanOut) {
+        const limit = Math.sqrt(6 / (fanIn + fanOut));
+        const size = fanIn * fanOut;
+        const arr = new Float32Array(size);
+        for (let i = 0; i < size; i++) {
+            arr[i] = (secureRandom() * 2 - 1) * limit;
+        }
+        return arr;
+    }
+    /** Random uniform initialization in [-0.5, 0.5] */
+    randomInit(rows, cols) {
+        const size = rows * cols;
+        const arr = new Float32Array(size);
+        for (let i = 0; i < size; i++) {
+            arr[i] = secureRandom() - 0.5;
+        }
+        return arr;
+    }
+    /** Sigmoid activation */
+    sigmoid(x) {
+        return 1 / (1 + Math.exp(-x));
+    }
+    /** Softmax activation */
+    softmax(logits) {
+        const max = Math.max(...Array.from(logits));
+        const exps = new Float32Array(logits.length);
+        let sum = 0;
+        for (let i = 0; i < logits.length; i++) {
+            exps[i] = Math.exp(logits[i] - max);
+            sum += exps[i];
+        }
+        for (let i = 0; i < exps.length; i++) {
+            exps[i] /= sum;
+        }
+        return exps;
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a new E-prop network with the given configuration.
+ */
+export function createEpropNetwork(config) {
+    return new EpropNetwork(config);
+}
+//# sourceMappingURL=eprop-learner.js.map

package/dist/integrations/ruvector/feature-flags.d.ts

@@ -189,6 +189,118 @@ export interface RuVectorFeatureFlags {
      * @default true
      */
     useReasoningQEC: boolean;
+    /**
+     * Enable HDC Pattern Fingerprinting (R1, ADR-087)
+     * Uses 10,000-bit binary hypervectors with XOR binding for O(1) compositional
+     * pattern fingerprinting and nanosecond Hamming-distance similarity.
+     * TypeScript fallback; WASM upgrade path via @ruvector/hdc-wasm.
+     * @default true
+     */
+    useHDCFingerprinting: boolean;
+    /**
+     * Enable CUSUM Drift Detection (R2, ADR-087)
+     * Adds statistical change-point detection to the coherence gate using
+     * two-sided Cumulative Sum (CUSUM) algorithm. Replaces heuristic thresholds
+     * with statistically rigorous drift detection per gate type.
+     * @default true
+     */
+    useCusumDriftDetection: boolean;
+    /**
+     * Enable Delta Event Sourcing (R3, ADR-087)
+     * Tracks pattern version history as delta events in SQLite. Enables rollback
+     * to any previous pattern state and incremental sync between agents.
+     * @default true
+     */
+    useDeltaEventSourcing: boolean;
+    /**
+     * Enable EWC++ Regularization (ADR-087)
+     * Activates Elastic Weight Consolidation++ Fisher Information Matrix
+     * computation in domain coordinators. Prevents catastrophic forgetting
+     * when learning new domains. Requires useSONAThreeLoop to be enabled.
+     * @default true
+     */
+    useEwcPlusPlusRegularization: boolean;
+    /**
+     * Enable GraphMAE Self-Supervised Embeddings (R4, ADR-087)
+     * Zero-label graph learning via masked graph autoencoders. Produces embeddings
+     * from code dependency graph structure without labeled training data.
+     * Consumer: coordinator-gnn.ts generateGraphMAEEmbeddings()
+     * Activation: enable after verifying 1K-node embedding quality in your graph
+     * @default false
+     */
+    useGraphMAEEmbeddings: boolean;
+    /**
+     * Enable Modern Hopfield Memory (R5, ADR-087)
+     * Exponential-capacity associative memory for exact pattern recall.
+     * Complements HNSW approximate search with content-addressable exact retrieval.
+     * Consumer: pattern-store.ts store()/search() exact recall path
+     * Activation: enable after verifying recall accuracy at your pattern count
+     * Note: at beta=8 with normalized patterns, softmax recall is equivalent
+     * to a single Hopfield fixed-point iteration (Ramsauer 2020, Theorem 3)
+     * @default false
+     */
+    useHopfieldMemory: boolean;
+    /**
+     * Enable Cold-Tier GNN Training (R6, ADR-087)
+     * LRU-cached mini-batch GNN training for graphs exceeding hotsetSize.
+     * FileBackedGraph available for true disk-backed larger-than-RAM graphs.
+     * Consumer: coordinator-gnn.ts trainWithColdTier()
+     * Activation: enable when pattern graph exceeds 10K nodes
+     * @default false
+     */
+    useColdTierGNN: boolean;
+    /**
+     * Enable Meta-Learning Enhancements (R7, ADR-087)
+     * Adds DecayingBeta, PlateauDetector, ParetoFront, and CuriosityBonus
+     * to the cross-domain transfer engine for adaptive exploration.
+     * Consumer: domain-transfer.ts DomainTransferEngine
+     * Activation: enable after verifying plateau detection on transfer history
+     * @default false
+     */
+    useMetaLearningEnhancements: boolean;
+    /**
+     * Enable Sublinear Solver (R8, ADR-087)
+     * O(log n) PageRank for graph-based pattern importance scoring.
+     * TypeScript power-iteration fallback; native @ruvector/solver-node optional.
+     * Consumer: pattern-promotion.ts (future integration)
+     * Activation: enable after bootstrapping a pattern citation graph
+     * @default false
+     */
+    useSublinearSolver: boolean;
+    /**
+     * Enable Spectral Graph Sparsification (R9, ADR-087)
+     * Effective resistance sampling to compress graphs while preserving
+     * Laplacian spectral properties. Reduces cost of graph operations.
+     * Consumer: coherence checks, mincut analysis (future integration)
+     * Activation: enable when graph edge count exceeds 10K
+     * @default false
+     */
+    useSpectralSparsification: boolean;
+    /**
+     * Enable Reservoir Replay with Coherence Gating (R10, ADR-087)
+     * Fixed-size replay buffer with coherence-gated admission and
+     * tier-weighted sampling. Uses CUSUM for drift-aware threshold.
+     * Consumer: experience-replay.ts (future integration)
+     * Activation: enable after verifying admission quality on your workload
+     * @default false
+     */
+    useReservoirReplay: boolean;
+    /**
+     * Enable E-prop Online Learning (R11, ADR-087)
+     * Eligibility propagation with 12 bytes/synapse, no backprop required.
+     * Registers as RL algorithm #10 in the suite.
+     * Consumer: rl-suite algorithms/eprop.ts
+     * @default false
+     */
+    useEpropOnlineLearning: boolean;
+    /**
+     * Enable Granger Causality for Test Failure Prediction (R12, ADR-087)
+     * Discovers causal chains in test execution history using VAR + F-test.
+     * Complements STDP (real-time) with batch historical analysis.
+     * Consumer: defect-intelligence domain
+     * @default false
+     */
+    useGrangerCausality: boolean;
 }
 /**
  * Default feature flags - all enabled by default
@@ -341,6 +453,71 @@ export declare function isCoherenceActionGateEnabled(): boolean;
  * @returns true if useReasoningQEC flag is set
  */
 export declare function isReasoningQECEnabled(): boolean;
+/**
+ * Check if HDC Pattern Fingerprinting is enabled (R1, ADR-087)
+ * @returns true if useHDCFingerprinting flag is set
+ */
+export declare function isHDCFingerprintingEnabled(): boolean;
+/**
+ * Check if CUSUM Drift Detection is enabled (R2, ADR-087)
+ * @returns true if useCusumDriftDetection flag is set
+ */
+export declare function isCusumDriftDetectionEnabled(): boolean;
+/**
+ * Check if Delta Event Sourcing is enabled (R3, ADR-087)
+ * @returns true if useDeltaEventSourcing flag is set
+ */
+export declare function isDeltaEventSourcingEnabled(): boolean;
+/**
+ * Check if EWC++ Regularization is enabled (ADR-087)
+ * @returns true if useEwcPlusPlusRegularization flag is set
+ */
+export declare function isEwcPlusPlusEnabled(): boolean;
+/**
+ * Check if GraphMAE embeddings are enabled
+ * @returns true if useGraphMAEEmbeddings flag is set
+ */
+export declare function isGraphMAEEnabled(): boolean;
+/**
+ * Check if Hopfield memory is enabled
+ * @returns true if useHopfieldMemory flag is set
+ */
+export declare function isHopfieldMemoryEnabled(): boolean;
+/**
+ * Check if Cold-Tier GNN training is enabled
+ * @returns true if useColdTierGNN flag is set
+ */
+export declare function isColdTierGNNEnabled(): boolean;
+/**
+ * Check if Meta-Learning Enhancements are enabled (R7, ADR-087)
+ * @returns true if useMetaLearningEnhancements flag is set
+ */
+export declare function isMetaLearningEnabled(): boolean;
+/**
+ * Check if Sublinear Solver is enabled (R8, ADR-087)
+ * @returns true if useSublinearSolver flag is set
+ */
+export declare function isSublinearSolverEnabled(): boolean;
+/**
+ * Check if Spectral Sparsification is enabled (R9, ADR-087)
+ * @returns true if useSpectralSparsification flag is set
+ */
+export declare function isSpectralSparsificationEnabled(): boolean;
+/**
+ * Check if Reservoir Replay is enabled (R10, ADR-087)
+ * @returns true if useReservoirReplay flag is set
+ */
+export declare function isReservoirReplayEnabled(): boolean;
+/**
+ * Check if E-prop Online Learning is enabled (R11, ADR-087)
+ * @returns true if useEpropOnlineLearning flag is set
+ */
+export declare function isEpropOnlineLearningEnabled(): boolean;
+/**
+ * Check if Granger Causality is enabled (R12, ADR-087)
+ * @returns true if useGrangerCausality flag is set
+ */
+export declare function isGrangerCausalityEnabled(): boolean;
 /**
  * Initialize feature flags from environment variables
  *