agentic-qe 3.8.11 → 3.8.13

package/dist/integrations/ruvector/solver-adapter.js

@@ -0,0 +1,299 @@
+/**
+ * Agentic QE v3 - PageRank Pattern Importance Solver (ADR-087, Milestone 3)
+ *
+ * Provides graph-based importance scoring for QE patterns using PageRank.
+ *
+ * Two execution paths:
+ * - **Native** (@ruvector/solver-node): O(log n) sublinear via Neumann series.
+ *   Requires the optional NAPI dependency to be installed.
+ * - **TypeScript fallback**: Standard power iteration, O(n * m * iterations).
+ *   Always available, correct results, linear-time.
+ *
+ * Usage:
+ * ```typescript
+ * import { createPageRankSolver } from './solver-adapter';
+ *
+ * const solver = createPageRankSolver({ dampingFactor: 0.85 });
+ * const scores = solver.computeImportance(graph);
+ * const ranked = solver.rankPatterns(graph);
+ * ```
+ *
+ * @module integrations/ruvector/solver-adapter
+ */
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_SOLVER_CONFIG = {
+    dampingFactor: 0.85,
+    tolerance: 1e-6,
+    maxIterations: 100,
+};
+// ============================================================================
+// Native Module Detection
+// ============================================================================
+/**
+ * Cached reference to the @ruvector/solver-node native module.
+ * `null` means we haven't attempted to load yet; `false` means load failed.
+ */
+let _nativeModule = null;
+/**
+ * Attempt to load the optional @ruvector/solver-node native bindings.
+ * The result is cached so the cost is paid at most once per process.
+ */
+function tryLoadNativeSync() {
+    if (_nativeModule === false)
+        return false;
+    if (_nativeModule != null)
+        return true;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _nativeModule = require('@ruvector/solver-node');
+        return true;
+    }
+    catch {
+        _nativeModule = false;
+        return false;
+    }
+}
+// ============================================================================
+// Input Validation
+// ============================================================================
+/**
+ * Validate a PatternGraph, throwing on invalid structure.
+ * Returns the number of nodes (N) for convenience.
+ */
+function validateGraph(graph) {
+    const n = graph.nodes.length;
+    for (const [from, to, weight] of graph.edges) {
+        if (from < 0 || from >= n) {
+            throw new RangeError(`Edge source index ${from} is out of bounds [0, ${n})`);
+        }
+        if (to < 0 || to >= n) {
+            throw new RangeError(`Edge target index ${to} is out of bounds [0, ${n})`);
+        }
+        if (!Number.isFinite(weight) || weight < 0) {
+            throw new RangeError(`Edge weight must be a non-negative finite number, got ${weight}`);
+        }
+    }
+    return n;
+}
+// ============================================================================
+// TypeScript Power-Iteration PageRank
+// ============================================================================
+/**
+ * Compute PageRank scores using the standard power-iteration method.
+ *
+ * Algorithm (per Wikipedia / original Brin-Page paper):
+ *   1. scores[i] = 1 / N  for all i
+ *   2. For each iteration:
+ *        new[i] = (1 - d) / N
+ *                 + d * SUM_{j -> i} ( scores[j] * edgeWeight(j,i) / weightedOutDegree[j] )
+ *   3. Converge when max |new[i] - old[i]| < tolerance
+ *
+ * Self-loops are included in outDegree computation but their contribution
+ * flows back to the same node (standard PageRank semantics).
+ *
+ * Dangling nodes (zero out-degree) distribute their score uniformly to all
+ * nodes, matching the standard random-surfer model.
+ */
+function powerIterationPageRank(graph, config) {
+    const n = graph.nodes.length;
+    const { dampingFactor: d, tolerance, maxIterations } = config;
+    // Pre-compute weighted out-degree for each node
+    const weightedOutDegree = new Float64Array(n);
+    for (const [from, , weight] of graph.edges) {
+        weightedOutDegree[from] += weight;
+    }
+    // Build adjacency list for incoming edges: inEdges[toIndex] = [[fromIndex, weight], ...]
+    const inEdges = new Array(n);
+    for (let i = 0; i < n; i++) {
+        inEdges[i] = [];
+    }
+    for (const [from, to, weight] of graph.edges) {
+        inEdges[to].push([from, weight]);
+    }
+    // Identify dangling nodes (no outgoing edges)
+    const danglingNodes = [];
+    for (let i = 0; i < n; i++) {
+        if (weightedOutDegree[i] === 0) {
+            danglingNodes.push(i);
+        }
+    }
+    // Initialize scores uniformly
+    let scores = new Float64Array(n);
+    const uniformShare = 1 / n;
+    scores.fill(uniformShare);
+    const base = (1 - d) / n;
+    for (let iter = 0; iter < maxIterations; iter++) {
+        // Dangling node contribution: their total score is redistributed uniformly
+        let danglingSum = 0;
+        for (const di of danglingNodes) {
+            danglingSum += scores[di];
+        }
+        const danglingContrib = d * danglingSum / n;
+        const next = new Float64Array(n);
+        for (let i = 0; i < n; i++) {
+            let incoming = 0;
+            for (const [from, weight] of inEdges[i]) {
+                incoming += (scores[from] * weight) / weightedOutDegree[from];
+            }
+            next[i] = base + d * incoming + danglingContrib;
+        }
+        // Check convergence (L-infinity norm)
+        let maxDelta = 0;
+        for (let i = 0; i < n; i++) {
+            const delta = Math.abs(next[i] - scores[i]);
+            if (delta > maxDelta)
+                maxDelta = delta;
+        }
+        scores = next;
+        if (maxDelta < tolerance) {
+            break;
+        }
+    }
+    return scores;
+}
+// ============================================================================
+// PageRankSolver Class
+// ============================================================================
+/**
+ * Computes importance scores for pattern graphs using PageRank.
+ *
+ * Prefers the native @ruvector/solver-node NAPI bindings when available
+ * (O(log n) via Neumann series). Falls back to a TypeScript power-iteration
+ * implementation (O(n * m * iterations)) when the native module is absent.
+ */
+export class PageRankSolver {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_SOLVER_CONFIG, ...config };
+        // Validate config ranges
+        if (this.config.dampingFactor <= 0 || this.config.dampingFactor >= 1) {
+            throw new RangeError('dampingFactor must be in (0, 1)');
+        }
+        if (this.config.tolerance <= 0) {
+            throw new RangeError('tolerance must be positive');
+        }
+        if (this.config.maxIterations < 1) {
+            throw new RangeError('maxIterations must be >= 1');
+        }
+        // Eagerly attempt native load so isNativeAvailable() is stable
+        tryLoadNativeSync();
+    }
+    /**
+     * Check whether the native @ruvector/solver-node module is available.
+     */
+    isNativeAvailable() {
+        return tryLoadNativeSync();
+    }
+    /**
+     * Compute importance scores for all nodes in a pattern graph.
+     *
+     * @param graph - The pattern graph to analyze
+     * @returns Map from node ID to its importance score (scores sum to ~1.0)
+     */
+    computeImportance(graph) {
+        const n = validateGraph(graph);
+        const result = new Map();
+        // Empty graph: nothing to score
+        if (n === 0) {
+            return result;
+        }
+        // Single node: trivially 1.0
+        if (n === 1) {
+            result.set(graph.nodes[0], 1.0);
+            return result;
+        }
+        let scores;
+        if (this.isNativeAvailable() && _nativeModule?.pagerank) {
+            // Delegate to native solver
+            scores = this.computeNative(graph);
+        }
+        else {
+            // TypeScript power iteration fallback
+            scores = powerIterationPageRank(graph, this.config);
+        }
+        for (let i = 0; i < n; i++) {
+            result.set(graph.nodes[i], scores[i]);
+        }
+        return result;
+    }
+    /**
+     * Rank all patterns in the graph by importance, highest first.
+     *
+     * @param graph - The pattern graph to analyze
+     * @returns Array of ImportanceScore sorted by score descending
+     */
+    rankPatterns(graph) {
+        const scores = this.computeImportance(graph);
+        const ranked = [];
+        for (const [patternId, score] of scores) {
+            ranked.push({ patternId, score, rank: 0 });
+        }
+        // Sort descending by score, stable by patternId for ties
+        ranked.sort((a, b) => {
+            if (b.score !== a.score)
+                return b.score - a.score;
+            return a.patternId.localeCompare(b.patternId);
+        });
+        // Assign ranks (1-based)
+        for (let i = 0; i < ranked.length; i++) {
+            ranked[i].rank = i + 1;
+        }
+        return ranked;
+    }
+    // --------------------------------------------------------------------------
+    // Private: native solver delegation
+    // --------------------------------------------------------------------------
+    /**
+     * Delegate PageRank computation to the native @ruvector/solver-node module.
+     *
+     * The native API is expected to accept the graph in a compatible format
+     * and return a Float64Array of scores indexed by node position.
+     */
+    computeNative(graph) {
+        const n = graph.nodes.length;
+        // Build edge arrays in the format expected by native solver
+        const fromIndices = new Int32Array(graph.edges.length);
+        const toIndices = new Int32Array(graph.edges.length);
+        const weights = new Float64Array(graph.edges.length);
+        for (let i = 0; i < graph.edges.length; i++) {
+            fromIndices[i] = graph.edges[i][0];
+            toIndices[i] = graph.edges[i][1];
+            weights[i] = graph.edges[i][2];
+        }
+        try {
+            const result = _nativeModule.pagerank({
+                nodeCount: n,
+                fromIndices,
+                toIndices,
+                weights,
+                dampingFactor: this.config.dampingFactor,
+                tolerance: this.config.tolerance,
+                maxIterations: this.config.maxIterations,
+            });
+            // Expect Float64Array or plain number[]
+            if (result instanceof Float64Array) {
+                return result;
+            }
+            return Float64Array.from(result);
+        }
+        catch {
+            // If native call fails, fall back gracefully to TS implementation
+            return powerIterationPageRank(graph, this.config);
+        }
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a PageRankSolver instance with the given configuration.
+ *
+ * @param config - Partial solver configuration (defaults applied)
+ * @returns A configured PageRankSolver
+ */
+export function createPageRankSolver(config) {
+    return new PageRankSolver(config);
+}
+//# sourceMappingURL=solver-adapter.js.map

package/dist/integrations/ruvector/sona-persistence.d.ts

@@ -184,6 +184,39 @@ export declare class PersistentSONAEngine {
      * Clear all in-memory patterns (does not affect SQLite)
      */
     clearMemory(): void;
+    /**
+     * Perform instant per-request MicroLoRA adaptation (Loop 1).
+     *
+     * Delegates to the three-loop engine's instant loop.
+     * Returns null if the three-loop engine is not initialized.
+     *
+     * @param requestFeatures - Feature vector for the current request
+     * @returns Adaptation result, or null if three-loop engine not initialized
+     */
+    instantAdapt(requestFeatures: number[]): import('./sona-three-loop.js').AdaptationResult | null;
+    /**
+     * Record the outcome of a request for REINFORCE-style gradient estimation (Loop 1b).
+     *
+     * Must be called after instantAdapt() with the reward signal.
+     * Delegates to the three-loop engine's recordOutcome().
+     *
+     * @param reward - Scalar reward (e.g., 1.0 for success, -1.0 for failure)
+     * @param requestIndex - Optional requestIndex from AdaptationResult for matching
+     */
+    recordOutcome(reward: number, requestIndex?: number): void;
+    /**
+     * Run background consolidation cycle (Loop 2).
+     *
+     * Delegates to the three-loop engine's background loop.
+     * Returns null if the three-loop engine is not initialized.
+     *
+     * @returns Consolidation result, or null if three-loop engine not initialized
+     */
+    backgroundConsolidate(): import('./sona-three-loop.js').ConsolidationResult | null;
+    /**
+     * Check if the three-loop engine is initialized and active.
+     */
+    isThreeLoopEnabled(): boolean;
     /**
      * Apply Micro-LoRA transformation
      */

package/dist/integrations/ruvector/sona-persistence.js

@@ -554,6 +554,53 @@ export class PersistentSONAEngine {
         this.baseEngine.clear();
     }
     // ==========================================================================
+    // Three-Loop Engine Pass-Through (instantAdapt -> recordOutcome -> backgroundConsolidate)
+    // ==========================================================================
+    /**
+     * Perform instant per-request MicroLoRA adaptation (Loop 1).
+     *
+     * Delegates to the three-loop engine's instant loop.
+     * Returns null if the three-loop engine is not initialized.
+     *
+     * @param requestFeatures - Feature vector for the current request
+     * @returns Adaptation result, or null if three-loop engine not initialized
+     */
+    instantAdapt(requestFeatures) {
+        this.ensureInitialized();
+        return this.baseEngine.instantAdapt(requestFeatures);
+    }
+    /**
+     * Record the outcome of a request for REINFORCE-style gradient estimation (Loop 1b).
+     *
+     * Must be called after instantAdapt() with the reward signal.
+     * Delegates to the three-loop engine's recordOutcome().
+     *
+     * @param reward - Scalar reward (e.g., 1.0 for success, -1.0 for failure)
+     * @param requestIndex - Optional requestIndex from AdaptationResult for matching
+     */
+    recordOutcome(reward, requestIndex) {
+        this.ensureInitialized();
+        this.baseEngine.recordOutcome(reward, requestIndex);
+    }
+    /**
+     * Run background consolidation cycle (Loop 2).
+     *
+     * Delegates to the three-loop engine's background loop.
+     * Returns null if the three-loop engine is not initialized.
+     *
+     * @returns Consolidation result, or null if three-loop engine not initialized
+     */
+    backgroundConsolidate() {
+        this.ensureInitialized();
+        return this.baseEngine.backgroundConsolidate();
+    }
+    /**
+     * Check if the three-loop engine is initialized and active.
+     */
+    isThreeLoopEnabled() {
+        return this.baseEngine.isThreeLoopEnabled();
+    }
+    // ==========================================================================
     // Learning Operations (Delegates to base engine)
     // ==========================================================================
     /**

package/dist/integrations/ruvector/spectral-sparsifier.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Spectral Graph Sparsification (ADR-087, Milestone 3, R9)
+ *
+ * Spectral graph sparsifier using degree-based leverage score sampling.
+ *
+ * Compresses weighted undirected graphs while approximately preserving
+ * Laplacian spectral properties within a (1 +/- epsilon) factor.
+ *
+ * Algorithm overview:
+ *   1. Approximate leverage scores via degree-based heuristic:
+ *      leverage(u,v) ≈ w(u,v) * (1/deg_w(u) + 1/deg_w(v)).
+ *      This is a practical O(m) approximation — NOT true effective
+ *      resistance (which requires the Laplacian pseudoinverse, O(n^3)).
+ *   2. Sample each edge with probability proportional to its leverage
+ *      score, scaled to a target edge budget.
+ *   3. Rescale surviving edge weights by 1/p_e to keep expectations unbiased.
+ *   4. Validate by comparing top-k Laplacian eigenvalues of both graphs.
+ *
+ * Limitations: The degree-based heuristic can misjudge edges between
+ * high-degree nodes (retained when redundant) and low-degree bridges
+ * (dropped when structurally important). For production use on critical
+ * graphs, upgrade to JL-projected effective resistance or spanning-tree
+ * sampling when @ruvector/sparsifier-wasm becomes available.
+ *
+ * The implementation is fully synchronous --- matrix operations are fast
+ * enough in TypeScript for graphs up to ~10K nodes.
+ *
+ * @module integrations/ruvector/spectral-sparsifier
+ */
+/**
+ * A weighted undirected graph for sparsification.
+ * Edges are undirected: (a, b, w) and (b, a, w) are the same edge.
+ */
+export interface SparsifierGraph {
+    /** Number of nodes (nodes are labelled 0 .. nodeCount-1) */
+    nodeCount: number;
+    /** Edges as [nodeA, nodeB, weight] triples (undirected) */
+    edges: Array<[number, number, number]>;
+}
+/**
+ * Result of spectral validation comparing original and sparsified graphs.
+ */
+export interface SpectralValidation {
+    /** Whether the sparsified graph is within epsilon bounds */
+    isValid: boolean;
+    /**
+     * Ratio of eigenvalues (sparsified / original) for each of the top-k
+     * non-trivial eigenvalues. Valid when all ratios lie in [1-eps, 1+eps].
+     */
+    eigenvalueRatios: number[];
+    /** Number of edges in the original graph */
+    originalEdgeCount: number;
+    /** Number of edges in the sparsified graph */
+    sparsifiedEdgeCount: number;
+    /** Compression ratio: sparsifiedEdgeCount / originalEdgeCount */
+    compressionRatio: number;
+}
+/**
+ * Configuration for the spectral sparsifier.
+ */
+export interface SparsifierConfig {
+    /**
+     * Approximation quality parameter. Lower values preserve spectral
+     * properties more faithfully but retain more edges.
+     * @default 0.3
+     */
+    epsilon: number;
+    /**
+     * Optional seed for the internal PRNG. When provided, sparsification
+     * results are fully reproducible.
+     */
+    seed?: number;
+}
+/**
+ * Spectral graph sparsifier using degree-based leverage score sampling.
+ *
+ * Compresses a weighted undirected graph while approximately preserving the
+ * spectrum of its Laplacian. Uses a degree-based heuristic for leverage
+ * scores (not true effective resistance). The approximation quality is
+ * controlled by `epsilon`: eigenvalues of the sparsified Laplacian should
+ * lie within a (1 +/- epsilon) factor of the original.
+ */
+export declare class SpectralSparsifier {
+    private readonly epsilon;
+    private readonly seed;
+    constructor(config?: Partial<SparsifierConfig>);
+    /**
+     * Sparsify a graph while preserving spectral properties.
+     *
+     * @param graph - The input weighted undirected graph
+     * @returns A new graph with fewer edges whose Laplacian spectrum
+     *          approximates the original within (1 +/- epsilon).
+     */
+    sparsify(graph: SparsifierGraph): SparsifierGraph;
+    /**
+     * Validate that a sparsified graph preserves the spectral properties of
+     * the original. Compares the top-k non-trivial Laplacian eigenvalues.
+     *
+     * @param original - The original graph
+     * @param sparsified - The sparsified graph
+     * @returns Validation result including eigenvalue ratios and compression info
+     */
+    validateSpectral(original: SparsifierGraph, sparsified: SparsifierGraph): SpectralValidation;
+    /**
+     * Compute the dense graph Laplacian matrix L = D - W.
+     *
+     * For weighted undirected graphs, L[i][i] = sum of weights of edges
+     * incident to i, and L[i][j] = -w(i,j).
+     *
+     * @param graph - Input graph
+     * @returns n x n Laplacian matrix as number[][]
+     */
+    computeLaplacian(graph: SparsifierGraph): number[][];
+    /**
+     * Compute the top-k eigenvalues of a symmetric matrix using power
+     * iteration with deflation.
+     *
+     * Eigenvalues are returned in descending order.
+     *
+     * @param matrix - Symmetric n x n matrix
+     * @param k - Number of eigenvalues to compute
+     * @returns Array of up to k eigenvalues in descending order
+     */
+    computeTopEigenvalues(matrix: number[][], k: number): number[];
+    /**
+     * Approximate effective resistance for every edge using a leverage-score
+     * heuristic based on node degrees.
+     *
+     * For edge (u, v) with weight w:
+     *   R_eff(u, v) ~= 1/deg_w(u) + 1/deg_w(v)
+     *
+     * where deg_w(u) is the weighted degree of u.
+     * This is a rough but computationally cheap O(m) approximation that
+     * captures the intuition that edges between low-degree nodes have higher
+     * effective resistance.
+     */
+    private approximateEffectiveResistances;
+    /**
+     * Single round of power iteration to find the dominant eigenvalue/vector,
+     * deflating away previously found eigenvectors.
+     *
+     * Uses a deterministic but well-spread initial vector and handles
+     * near-zero eigenvalues by checking the matrix's remaining Frobenius norm.
+     */
+    private powerIteration;
+}
+/**
+ * Create a spectral sparsifier with the given configuration.
+ *
+ * @param config - Optional partial configuration
+ * @returns A new SpectralSparsifier instance
+ */
+export declare function createSpectralSparsifier(config?: Partial<SparsifierConfig>): SpectralSparsifier;
+//# sourceMappingURL=spectral-sparsifier.d.ts.map