agentic-qe 3.13.9 → 3.13.11

package/dist/learning/aqe-learning-engine.js

@@ -41,6 +41,7 @@ import { ok, err } from '../shared/types/index.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { safeJsonParse } from '../shared/safe-json.js';
 import { createQEReasoningBank, } from './qe-reasoning-bank.js';
+import { enhanceRoutingWithPatterns } from './pattern-routing-guidance.js';
 import { PROMOTION_THRESHOLD } from './qe-patterns.js';
 import { createClaudeFlowBridge, } from '../adapters/claude-flow/index.js';
 import { createExperienceCaptureService, } from './experience-capture.js';
@@ -351,7 +352,7 @@ export class AQELearningEngine {
         }
         // Enhance routing result with pattern context (Phase 5.2)
         if (localResult.success && patternSearchResult.success) {
-            const enhancedResult = this.enhanceRoutingWithPatterns(localResult.value, patternSearchResult.value);
+            const enhancedResult = enhanceRoutingWithPatterns(localResult.value, patternSearchResult.value);
             return ok(enhancedResult);
         }
         return localResult;
@@ -429,41 +430,6 @@ export class AQELearningEngine {
      * @param patterns - Found patterns
      * @returns Enhanced routing result
      */
-    enhanceRoutingWithPatterns(routingResult, patterns) {
-        // Filter to high-quality patterns only
-        const relevantPatterns = patterns.filter(p => p.similarity >= 0.5 && p.pattern.qualityScore >= 0.3);
-        if (relevantPatterns.length === 0) {
-            return routingResult;
-        }
-        // Generate pattern hints for agent prompts
-        const patternHints = relevantPatterns.map(result => {
-            const pattern = result.pattern;
-            return `[Pattern: ${pattern.name}] ${pattern.description} (confidence: ${(pattern.confidence * 100).toFixed(0)}%, similarity: ${(result.similarity * 100).toFixed(0)}%)`;
-        });
-        // Add pattern-based guidance to existing guidance
-        const enhancedGuidance = [
-            ...routingResult.guidance,
-            '--- Relevant Patterns ---',
-            ...patternHints,
-        ];
-        // Include pattern objects in result for downstream use
-        const enhancedPatterns = [
-            ...routingResult.patterns,
-            ...relevantPatterns.map(r => r.pattern),
-        ];
-        // Build enhanced reasoning
-        const patternReasoning = relevantPatterns.length > 0
-            ? `; Found ${relevantPatterns.length} relevant pattern(s) with avg similarity ${(relevantPatterns.reduce((sum, p) => sum + p.similarity, 0) / relevantPatterns.length * 100).toFixed(0)}%`
-            : '';
-        return {
-            ...routingResult,
-            patterns: enhancedPatterns,
-            guidance: enhancedGuidance,
-            reasoning: routingResult.reasoning + patternReasoning,
-            // Boost confidence slightly when relevant patterns are found
-            confidence: Math.min(1, routingResult.confidence + relevantPatterns.length * 0.02),
-        };
-    }
     // ==========================================================================
     // Model Routing (CF Enhanced)
     // ==========================================================================

package/dist/learning/pattern-lifecycle.js

@@ -638,7 +638,7 @@ Pattern extracted from ${exp.count} successful experiences.`;
                   ELSE 0.0 END)))),
           updated_at = datetime('now')
       WHERE deprecated_at IS NULL
-        AND (last_used_at IS NULL OR datetime(last_used_at) < datetime(?, 'unixepoch'))
+        AND datetime(COALESCE(last_used_at, created_at)) < datetime(?, 'unixepoch')
     `).run(this.config.minActiveConfidence, baseDecayAmount, EWC_DECAY_PROTECTION, EWC_MIN_USAGE_FOR_PROTECTION, cutoffTime / 1000);
         return {
             updated: result.changes,

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-routing-guidance.d.ts

@@ -0,0 +1,16 @@
+import type { QERoutingResult } from './qe-reasoning-bank-types.js';
+import type { QEPattern } from './qe-patterns.js';
+export declare const ROUTING_PATTERN_SIMILARITY_FLOOR = 0.5;
+export declare const ROUTING_PATTERN_QUALITY_FLOOR = 0.3;
+/**
+ * Add actionable learned-pattern context to an existing routing result.
+ * This is pure composition: callers retain ownership of the initialized store.
+ */
+export interface RoutingPatternMatch {
+    pattern: QEPattern;
+    similarity: number;
+}
+export declare function enhanceRoutingWithPatterns<T extends QERoutingResult>(routingResult: T, patternResults: RoutingPatternMatch[]): T;
+/** Preserve legacy routing output unless the caller explicitly enables learned guidance. */
+export declare function maybeEnhanceRoutingWithPatterns<T extends QERoutingResult>(enabled: boolean | undefined, routingResult: T, patternResults: RoutingPatternMatch[]): T;
+//# sourceMappingURL=pattern-routing-guidance.d.ts.map

package/dist/learning/pattern-routing-guidance.js

@@ -0,0 +1,34 @@
+export const ROUTING_PATTERN_SIMILARITY_FLOOR = 0.5;
+export const ROUTING_PATTERN_QUALITY_FLOOR = 0.3;
+export function enhanceRoutingWithPatterns(routingResult, patternResults) {
+    const relevantPatterns = patternResults.filter(({ pattern, similarity }) => similarity >= ROUTING_PATTERN_SIMILARITY_FLOOR
+        && pattern.qualityScore >= ROUTING_PATTERN_QUALITY_FLOOR);
+    if (relevantPatterns.length === 0)
+        return routingResult;
+    const patternHints = relevantPatterns.map(({ pattern, similarity }) => `[Pattern: ${pattern.name}] ${pattern.description} `
+        + `(confidence: ${(pattern.confidence * 100).toFixed(0)}%, `
+        + `similarity: ${(similarity * 100).toFixed(0)}%)`);
+    const existingPatternIds = new Set(routingResult.patterns.map(({ id }) => id));
+    const additionalPatterns = relevantPatterns
+        .map(({ pattern }) => pattern)
+        .filter(({ id }) => !existingPatternIds.has(id));
+    const avgSimilarity = relevantPatterns.reduce((sum, result) => sum + result.similarity, 0)
+        / relevantPatterns.length;
+    return {
+        ...routingResult,
+        patterns: [...routingResult.patterns, ...additionalPatterns],
+        guidance: [
+            ...routingResult.guidance,
+            '--- Relevant Patterns ---',
+            ...patternHints,
+        ],
+        reasoning: `${routingResult.reasoning}; Found ${relevantPatterns.length} relevant pattern(s) `
+            + `with avg similarity ${(avgSimilarity * 100).toFixed(0)}%`,
+        confidence: Math.min(1, routingResult.confidence + relevantPatterns.length * 0.02),
+    };
+}
+/** Preserve legacy routing output unless the caller explicitly enables learned guidance. */
+export function maybeEnhanceRoutingWithPatterns(enabled, routingResult, patternResults) {
+    return enabled ? enhanceRoutingWithPatterns(routingResult, patternResults) : routingResult;
+}
+//# sourceMappingURL=pattern-routing-guidance.js.map

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

@@ -57,6 +57,8 @@ export interface QERoutingRequest {
     capabilities?: string[];
     /** Context for matching */
     context?: Partial<QEPatternContext>;
+    /** Append relevant learned patterns to guidance (opt-in for compatibility). */
+    includePatternGuidance?: boolean;
 }
 /**
  * Task routing result
@@ -142,6 +144,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

@@ -29,6 +29,7 @@ import { AGENT_CAPABILITIES, calculateAgentScores, applyExplorationPolicy, resol
 import { resolveTopologyCriticalFromSharedMincut } from './routing-topology-gate.js';
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { resizeEmbedding, hashEmbedding } from './embedding-utils.js';
+import { maybeEnhanceRoutingWithPatterns } from './pattern-routing-guidance.js';
 import { checkPatternPromotionWithCoherence, promotePattern as promotePatternFn, seedCrossDomainPatterns as seedCrossDomainPatternsFn, } from './pattern-promotion.js';
 // ============================================================================
 // QEReasoningBank Implementation
@@ -366,6 +367,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
      */
@@ -480,7 +495,7 @@ export class QEReasoningBank {
                 criticality: safetyMultiplier,
                 qWeight: avgQWeight,
             };
-            return ok(result);
+            return ok(maybeEnhanceRoutingWithPatterns(request.includePatternGuidance, result, patternResults.success ? patternResults.value : []));
         }
         catch (error) {
             return err(toError(error));

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

@@ -36,6 +36,8 @@ export interface RealQERoutingRequest {
     domain?: QEDomain;
     capabilities?: string[];
     context?: Partial<QEPatternContext>;
+    /** Append relevant learned patterns to guidance (opt-in for compatibility). */
+    includePatternGuidance?: boolean;
 }
 export interface RealQERoutingResult {
     recommendedAgent: string;

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

@@ -18,6 +18,7 @@
 import { v4 as uuidv4 } from 'uuid';
 import { LoggerFactory } from '../logging/index.js';
 import { toError, toErrorMessage } from '../shared/error-utils.js';
+import { maybeEnhanceRoutingWithPatterns } from './pattern-routing-guidance.js';
 const logger = LoggerFactory.create('RealQEReasoningBank');
 import { computeRealEmbedding, isTransformerAvailable, getEmbeddingDimension, clearEmbeddingCache, } from './real-embeddings.js';
 import { createSQLitePatternStore, } from './sqlite-persistence.js';
@@ -507,7 +508,7 @@ export class RealQEReasoningBank {
             this.stats.totalRoutingLatency += latencyMs;
             // CircularBuffer handles bounded size automatically - O(1) operation
             this.routingLatencies.push(latencyMs);
-            return ok({
+            const result = {
                 recommendedAgent: recommended.agent,
                 confidence: recommended.score,
                 alternatives: alternatives.map(a => ({ agent: a.agent, score: a.score })),
@@ -516,7 +517,8 @@ export class RealQEReasoningBank {
                 guidance,
                 reasoning: recommended.reasoning.join('; '),
                 latencyMs,
-            });
+            };
+            return ok(maybeEnhanceRoutingWithPatterns(request.includePatternGuidance, result, searchResult.success ? searchResult.value : []));
         }
         catch (error) {
             return err(toError(error));

package/dist/learning/token-tracker.js

@@ -11,7 +11,7 @@
  *
  * @example
  * ```typescript
- * import { TokenMetricsCollector } from './token-tracker';
+ * import { TokenMetricsCollector } from './token-tracker.js';
  *
  * // Record token usage for a task
  * TokenMetricsCollector.recordTokenUsage('task-123', 'agent-1', 'test-generation', 'generate', {

package/dist/logging/index.js

@@ -7,7 +7,7 @@
  *
  * Usage:
  * ```typescript
- * import { LoggerFactory, LogLevel } from '../logging';
+ * import { LoggerFactory, LogLevel } from '../logging/index.js';
  *
  * // Configure (typically at application startup)
  * LoggerFactory.setLevel(LogLevel.DEBUG);

package/dist/logging/logger-factory.js

@@ -21,7 +21,7 @@ const DEFAULT_FACTORY_CONFIG = {
  *
  * Usage:
  * ```typescript
- * import { LoggerFactory } from '../logging';
+ * import { LoggerFactory } from '../logging/index.js';
  *
  * // Set global log level
  * LoggerFactory.setLevel(LogLevel.DEBUG);