agentic-qe 3.13.8 → 3.13.10

package/dist/integrations/ruvector/solver-adapter.d.ts

@@ -4,8 +4,8 @@
  * 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.
+ * - **Async**: optional @ruvector/solver NAPI backend, then worker-thread
+ *   TypeScript fallback for large graphs.
  * - **TypeScript fallback**: Standard power iteration, O(n * m * iterations).
  *   Always available, correct results, linear-time.
  *
@@ -20,45 +20,43 @@
  *
  * @module integrations/ruvector/solver-adapter
  */
+import { type AsyncPageRankRunner, type NativeSolverModule, type PatternGraph, type SolverConfig } from './page-rank-backends.js';
+export type { PatternGraph, SolverConfig } from './page-rank-backends.js';
 /**
  * A directed graph of pattern relationships for importance scoring.
  *
  * Nodes represent pattern IDs; edges encode directed relationships
  * (e.g., "pattern A depends on pattern B") with numeric weights.
  */
-export interface PatternGraph {
-    /** Node IDs (pattern IDs) */
-    nodes: string[];
-    /** Directed edges: [fromIndex, toIndex, weight] */
-    edges: Array<[number, number, number]>;
-}
 /** Result of importance scoring for a single pattern */
 export interface ImportanceScore {
     patternId: string;
     score: number;
     rank: number;
 }
-/** Configuration for the solver */
-export interface SolverConfig {
-    /** Damping factor for PageRank (default: 0.85) */
-    dampingFactor: number;
-    /** Convergence tolerance (default: 1e-6) */
-    tolerance: number;
-    /** Maximum iterations for power iteration fallback (default: 100) */
-    maxIterations: number;
+export interface PageRankRuntimeOptions {
+    /** Minimum nodes + edges before using a worker (default: 50,000). */
+    workerThreshold: number;
+    /** Worker timeout before synchronous fallback (default: 30 seconds). */
+    workerTimeoutMs: number;
+    /** Dependency-injection seam for tests and alternative worker runners. */
+    workerRunner: AsyncPageRankRunner;
+    /** Override native discovery; null explicitly disables the native backend. */
+    nativeModule?: NativeSolverModule | null;
 }
 /**
  * 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.
+ * The synchronous API uses the deterministic TypeScript implementation.
+ * The async API prefers @ruvector/solver and offloads large fallback graphs.
  */
 export declare class PageRankSolver {
     private readonly config;
-    constructor(config?: Partial<SolverConfig>);
+    private readonly runtime;
+    private readonly nativeModule;
+    constructor(config?: Partial<SolverConfig>, runtime?: Partial<PageRankRuntimeOptions>);
     /**
-     * Check whether the native @ruvector/solver-node module is available.
+     * Check whether the native @ruvector/solver module is available.
      */
     isNativeAvailable(): boolean;
     /**
@@ -68,6 +66,11 @@ export declare class PageRankSolver {
      * @returns Map from node ID to its importance score (scores sum to ~1.0)
      */
     computeImportance(graph: PatternGraph): Map<string, number>;
+    /**
+     * Compute PageRank without blocking the event loop for large graphs.
+     * Native and worker failures fall back to the verified synchronous backend.
+     */
+    computeImportanceAsync(graph: PatternGraph): Promise<Map<string, number>>;
     /**
      * Rank all patterns in the graph by importance, highest first.
      *
@@ -75,13 +78,7 @@ export declare class PageRankSolver {
      * @returns Array of ImportanceScore sorted by score descending
      */
     rankPatterns(graph: PatternGraph): ImportanceScore[];
-    /**
-     * 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.
-     */
-    private computeNative;
+    private copyScoresToResult;
 }
 /**
  * Create a PageRankSolver instance with the given configuration.
@@ -89,5 +86,5 @@ export declare class PageRankSolver {
  * @param config - Partial solver configuration (defaults applied)
  * @returns A configured PageRankSolver
  */
-export declare function createPageRankSolver(config?: Partial<SolverConfig>): PageRankSolver;
+export declare function createPageRankSolver(config?: Partial<SolverConfig>, runtime?: Partial<PageRankRuntimeOptions>): PageRankSolver;
 //# sourceMappingURL=solver-adapter.d.ts.map

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

@@ -4,8 +4,8 @@
  * 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.
+ * - **Async**: optional @ruvector/solver NAPI backend, then worker-thread
+ *   TypeScript fallback for large graphs.
  * - **TypeScript fallback**: Standard power iteration, O(n * m * iterations).
  *   Always available, correct results, linear-time.
  *
@@ -20,6 +20,7 @@
  *
  * @module integrations/ruvector/solver-adapter
  */
+import { computeTypeScriptPageRank, loadNativeSolverModule, runNativePageRank, runPageRankWorker, } from './page-rank-backends.js';
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -28,33 +29,11 @@ const DEFAULT_SOLVER_CONFIG = {
     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;
-    }
-}
+const DEFAULT_RUNTIME_OPTIONS = {
+    workerThreshold: 50_000,
+    workerTimeoutMs: 30_000,
+    workerRunner: runPageRankWorker,
+};
 // ============================================================================
 // Input Validation
 // ============================================================================
@@ -78,95 +57,24 @@ function validateGraph(graph) {
     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.
+ * The synchronous API uses the deterministic TypeScript implementation.
+ * The async API prefers @ruvector/solver and offloads large fallback graphs.
  */
 export class PageRankSolver {
     config;
-    constructor(config) {
+    runtime;
+    nativeModule;
+    constructor(config, runtime) {
         this.config = { ...DEFAULT_SOLVER_CONFIG, ...config };
+        this.runtime = { ...DEFAULT_RUNTIME_OPTIONS, ...runtime };
+        this.nativeModule = runtime && 'nativeModule' in runtime
+            ? runtime.nativeModule ?? null
+            : loadNativeSolverModule();
         // Validate config ranges
         if (this.config.dampingFactor <= 0 || this.config.dampingFactor >= 1) {
             throw new RangeError('dampingFactor must be in (0, 1)');
@@ -177,14 +85,18 @@ export class PageRankSolver {
         if (this.config.maxIterations < 1) {
             throw new RangeError('maxIterations must be >= 1');
         }
-        // Eagerly attempt native load so isNativeAvailable() is stable
-        tryLoadNativeSync();
+        if (this.runtime.workerThreshold < 0) {
+            throw new RangeError('workerThreshold must be >= 0');
+        }
+        if (this.runtime.workerTimeoutMs < 1) {
+            throw new RangeError('workerTimeoutMs must be >= 1');
+        }
     }
     /**
-     * Check whether the native @ruvector/solver-node module is available.
+     * Check whether the native @ruvector/solver module is available.
      */
     isNativeAvailable() {
-        return tryLoadNativeSync();
+        return this.nativeModule !== null;
     }
     /**
      * Compute importance scores for all nodes in a pattern graph.
@@ -204,18 +116,35 @@ export class PageRankSolver {
             result.set(graph.nodes[0], 1.0);
             return result;
         }
+        const scores = computeTypeScriptPageRank(graph, this.config);
+        this.copyScoresToResult(graph, scores, result);
+        return result;
+    }
+    /**
+     * Compute PageRank without blocking the event loop for large graphs.
+     * Native and worker failures fall back to the verified synchronous backend.
+     */
+    async computeImportanceAsync(graph) {
+        const n = validateGraph(graph);
+        if (n < 2)
+            return this.computeImportance(graph);
         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);
+        try {
+            if (this.nativeModule) {
+                scores = await runNativePageRank(this.nativeModule, graph, this.config);
+            }
+            else if (graph.nodes.length + graph.edges.length >= this.runtime.workerThreshold) {
+                scores = await this.runtime.workerRunner(graph, this.config, this.runtime.workerTimeoutMs);
+            }
+            else {
+                scores = computeTypeScriptPageRank(graph, this.config);
+            }
         }
-        for (let i = 0; i < n; i++) {
-            result.set(graph.nodes[i], scores[i]);
+        catch {
+            scores = computeTypeScriptPageRank(graph, this.config);
         }
+        const result = new Map();
+        this.copyScoresToResult(graph, scores, result);
         return result;
     }
     /**
@@ -242,45 +171,9 @@ export class PageRankSolver {
         }
         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);
+    copyScoresToResult(graph, scores, result) {
+        for (let i = 0; i < graph.nodes.length; i++) {
+            result.set(graph.nodes[i], scores[i]);
         }
     }
 }
@@ -293,7 +186,7 @@ export class PageRankSolver {
  * @param config - Partial solver configuration (defaults applied)
  * @returns A configured PageRankSolver
  */
-export function createPageRankSolver(config) {
-    return new PageRankSolver(config);
+export function createPageRankSolver(config, runtime) {
+    return new PageRankSolver(config, runtime);
 }
 //# sourceMappingURL=solver-adapter.js.map

package/dist/learning/pattern-promotion.d.ts

@@ -45,7 +45,7 @@ export declare function checkPatternPromotionWithCoherence(pattern: QEPattern, d
 /**
  * Promote a pattern to long-term storage
  */
-export declare function promotePattern(patternId: string, deps: PromotionDeps): Promise<void>;
+export declare function promotePattern(patternId: string, deps: PromotionDeps): Promise<Result<void>>;
 /**
  * Dependencies for cross-domain seeding
  */
@@ -129,4 +129,14 @@ export declare function computeBlendedImportance(patterns: Array<{
     usageCount: number;
     successRate: number;
 }>, citationGraph: PatternGraph, alpha?: number): Map<string, number>;
+/**
+ * Async counterpart that offloads large graphs and can use the optional
+ * RuVector NAPI backend without changing existing synchronous callers.
+ */
+export declare function computeBlendedImportanceAsync(patterns: Array<{
+    id: string;
+    confidence: number;
+    usageCount: number;
+    successRate: number;
+}>, citationGraph: PatternGraph, alpha?: number): Promise<Map<string, number>>;
 //# sourceMappingURL=pattern-promotion.d.ts.map

package/dist/learning/pattern-promotion.js

@@ -142,9 +142,11 @@ export async function promotePattern(patternId, deps) {
                 payload: { patternId, newTier: 'long-term' },
             });
         }
+        return result;
     }
     else {
         logger.error('Failed to promote pattern', result.error, { patternId });
+        return result;
     }
 }
 /**
@@ -415,6 +417,31 @@ export function computeBlendedImportance(patterns, citationGraph, alpha = 0.3) {
     }
     const solver = new PageRankSolver();
     const pageRankScores = solver.computeImportance(citationGraph);
+    return blendImportanceScores(patterns, citationGraph, qualityScores, pageRankScores, alpha);
+}
+/**
+ * Async counterpart that offloads large graphs and can use the optional
+ * RuVector NAPI backend without changing existing synchronous callers.
+ */
+export async function computeBlendedImportanceAsync(patterns, citationGraph, alpha = 0.3) {
+    const result = new Map();
+    if (!getRuVectorFeatureFlags().useSublinearSolver) {
+        for (const pattern of patterns)
+            result.set(pattern.id, calculateQualityScore(pattern));
+        return result;
+    }
+    const qualityScores = new Map();
+    for (const pattern of patterns) {
+        qualityScores.set(pattern.id, calculateQualityScore(pattern));
+    }
+    if (citationGraph.nodes.length < 3 || citationGraph.edges.length < 2) {
+        return qualityScores;
+    }
+    const pageRankScores = await new PageRankSolver().computeImportanceAsync(citationGraph);
+    return blendImportanceScores(patterns, citationGraph, qualityScores, pageRankScores, alpha);
+}
+function blendImportanceScores(patterns, citationGraph, qualityScores, pageRankScores, alpha) {
+    const result = new Map();
     for (const p of patterns) {
         const quality = qualityScores.get(p.id) ?? 0;
         const pageRank = pageRankScores.get(p.id) ?? 0;

package/dist/learning/pattern-usage-recorder.d.ts

@@ -27,6 +27,10 @@ export interface PatternUsageRecord {
     metrics?: Record<string, unknown>;
     feedback?: string;
 }
+export interface PatternUsageBatchRecord extends Omit<PatternUsageRecord, 'success'> {
+    usageCount: number;
+    successfulUses: number;
+}
 export interface PatternUsageResult {
     /**
      * Whether the helper found and updated the pattern row.
@@ -55,4 +59,10 @@ export interface PatternUsageResult {
  * level. Multiple concurrent callers on the same connection will queue.
  */
 export declare function recordPatternUsage(db: DatabaseType, record: PatternUsageRecord): PatternUsageResult;
+/**
+ * Record an aggregate of observed uses without bypassing the usage audit.
+ * One audit row is written per observed use, while the pattern counters are
+ * updated once in the same transaction.
+ */
+export declare function recordPatternUsageBatch(db: DatabaseType, record: PatternUsageBatchRecord): PatternUsageResult;
 //# sourceMappingURL=pattern-usage-recorder.d.ts.map

package/dist/learning/pattern-usage-recorder.js

@@ -69,4 +69,51 @@ export function recordPatternUsage(db, record) {
         qualityScore: newQualityScore,
     };
 }
+/**
+ * Record an aggregate of observed uses without bypassing the usage audit.
+ * One audit row is written per observed use, while the pattern counters are
+ * updated once in the same transaction.
+ */
+export function recordPatternUsageBatch(db, record) {
+    if (!Number.isInteger(record.usageCount) || record.usageCount < 1 ||
+        !Number.isInteger(record.successfulUses) || record.successfulUses < 0 ||
+        record.successfulUses > record.usageCount) {
+        throw new Error('Invalid aggregate pattern usage counts');
+    }
+    const pattern = db
+        .prepare('SELECT confidence, usage_count, successful_uses FROM qe_patterns WHERE id = ?')
+        .get(record.patternId);
+    if (!pattern)
+        return { updated: false };
+    const newUsageCount = pattern.usage_count + record.usageCount;
+    const newSuccessfulUses = pattern.successful_uses + record.successfulUses;
+    const newSuccessRate = newSuccessfulUses / newUsageCount;
+    const usageScore = Math.min(1, newUsageCount / 100);
+    const newQualityScore = pattern.confidence * 0.3 + usageScore * 0.2 + newSuccessRate * 0.5;
+    const insertUsage = db.prepare(`
+    INSERT INTO qe_pattern_usage (pattern_id, success, metrics_json, feedback)
+    VALUES (?, ?, ?, ?)
+  `);
+    const updatePattern = db.prepare(`
+    UPDATE qe_patterns SET
+      usage_count = ?, successful_uses = ?, success_rate = ?, quality_score = ?,
+      last_used_at = datetime('now'), updated_at = datetime('now')
+    WHERE id = ?
+  `);
+    const metricsJson = record.metrics ? JSON.stringify(record.metrics) : null;
+    const feedback = record.feedback ?? null;
+    db.transaction(() => {
+        for (let index = 0; index < record.usageCount; index++) {
+            insertUsage.run(record.patternId, index < record.successfulUses ? 1 : 0, metricsJson, feedback);
+        }
+        updatePattern.run(newUsageCount, newSuccessfulUses, newSuccessRate, newQualityScore, record.patternId);
+    })();
+    return {
+        updated: true,
+        usageCount: newUsageCount,
+        successfulUses: newSuccessfulUses,
+        successRate: newSuccessRate,
+        qualityScore: newQualityScore,
+    };
+}
 //# sourceMappingURL=pattern-usage-recorder.js.map

package/dist/learning/qe-reasoning-bank-types.d.ts

@@ -142,6 +142,8 @@ export interface IQEReasoningBank {
     getPattern(id: string): Promise<QEPattern | null>;
     /** Record pattern usage outcome */
     recordOutcome(outcome: LearningOutcome): Promise<Result<void>>;
+    /** Explicitly promote a stored pattern to long-term memory. */
+    promotePattern(patternId: string): Promise<Result<void>>;
     /** Route a task to optimal agent */
     routeTask(request: QERoutingRequest): Promise<Result<QERoutingResult>>;
     /** Get guidance for a domain */

package/dist/learning/qe-reasoning-bank.d.ts

@@ -110,6 +110,12 @@ export declare class QEReasoningBank implements IQEReasoningBank {
      * Record pattern usage outcome
      */
     recordOutcome(outcome: LearningOutcome): Promise<Result<void>>;
+    /**
+     * Explicitly promote a stored pattern to long-term memory.
+     * Eligibility is decided by the caller; persistence, audit, and events use
+     * the same path as automatic promotion.
+     */
+    promotePattern(patternId: string): Promise<Result<void>>;
     /**
      * Get promotion dependencies for the extracted promotion module
      */

package/dist/learning/qe-reasoning-bank.js

@@ -366,6 +366,20 @@ export class QEReasoningBank {
         }
         return result;
     }
+    /**
+     * Explicitly promote a stored pattern to long-term memory.
+     * Eligibility is decided by the caller; persistence, audit, and events use
+     * the same path as automatic promotion.
+     */
+    async promotePattern(patternId) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        if (!await this.getPattern(patternId)) {
+            return err(new Error(`Pattern not found: ${patternId}`));
+        }
+        return promotePatternFn(patternId, this.getPromotionDeps());
+    }
     /**
      * Get promotion dependencies for the extracted promotion module
      */