agentic-qe 3.7.22 → 3.8.0

package/dist/learning/experience-capture.js

@@ -15,6 +15,7 @@
 import { v4 as uuidv4 } from 'uuid';
 import { ok, err } from '../shared/types/index.js';
 import { LoggerFactory } from '../logging/index.js';
+import { getRuVectorFeatureFlags } from '../integrations/ruvector/feature-flags.js';
 const logger = LoggerFactory.create('experience-capture');
 import { PROMOTION_THRESHOLD } from './qe-patterns.js';
 /**
@@ -91,12 +92,21 @@ export class ExperienceCaptureService {
     };
     // Session-level counter (not persisted, tracks only this session)
     sessionCaptureCount = 0;
+    /** Optional witness chain for attaching audit receipts to experiences */
+    witnessChain;
     constructor(memory, patternStore, eventBus, config = {}) {
         this.memory = memory;
         this.patternStore = patternStore;
         this.eventBus = eventBus;
         this.config = { ...DEFAULT_EXPERIENCE_CONFIG, ...config };
     }
+    /**
+     * Set the witness chain for attaching audit receipts to captured experiences.
+     * Only creates witness records when the useWitnessChain feature flag is enabled.
+     */
+    setWitnessChain(chain) {
+        this.witnessChain = chain;
+    }
     /**
      * Initialize the experience capture service
      */
@@ -176,6 +186,30 @@ export class ExperienceCaptureService {
             experience.testOutcome = rawOutcome;
             experience.reward = computeBinaryReward(rawOutcome);
         }
+        // Attach witness receipt when witness chain is available and feature flag enabled
+        if (this.witnessChain && getRuVectorFeatureFlags().useWitnessChain) {
+            try {
+                const receipt = this.witnessChain.appendWitness({
+                    type: 'experience-capture',
+                    decision: experience.success ? 'PASS' : 'FAIL',
+                    context: {
+                        experienceId: experience.id,
+                        task: experience.task,
+                        quality: experience.quality,
+                        domain: experience.domain,
+                        reward: experience.reward,
+                    },
+                    evidence: experience.reward,
+                });
+                experience.witnessHash = receipt.hash;
+            }
+            catch (witnessError) {
+                logger.warn('Failed to create witness receipt for experience', {
+                    experienceId: experience.id,
+                    error: witnessError instanceof Error ? witnessError.message : String(witnessError),
+                });
+            }
+        }
         // Remove from active
         this.activeExperiences.delete(experienceId);
         // Store experience

package/dist/learning/index.d.ts

@@ -77,6 +77,8 @@ export { generateRemediationHints, findCommonKeywords, } from './opd-remediation
 export type { RemediationHint, RemediationCategory, RemediationConfig, PatternInput, ExecutionRecord, } from './opd-remediation.js';
 export { LearningMetricsTracker, createLearningMetricsTracker, } from './metrics-tracker.js';
 export type { LearningMetricsSnapshot, DashboardData, } from './metrics-tracker.js';
+export { RegretTracker, createRegretTracker, linearRegressionSlope, } from './regret-tracker.js';
+export type { RegretPoint, GrowthRate, DomainHealthSummary, RegretAlert, RegretAlertCallback, } from './regret-tracker.js';
 export { DailyLogger } from './daily-log.js';
 export type { DailyLogEntry, DailyLogConfig, } from './daily-log.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/learning/index.js

@@ -142,6 +142,10 @@ export { generateRemediationHints, findCommonKeywords, } from './opd-remediation
 // ============================================================================
 export { LearningMetricsTracker, createLearningMetricsTracker, } from './metrics-tracker.js';
 // ============================================================================
+// Regret Tracker (Task 2.4: Regret Tracking & Learning Health)
+// ============================================================================
+export { RegretTracker, createRegretTracker, linearRegressionSlope, } from './regret-tracker.js';
+// ============================================================================
 // Daily Log Tier (OpenClaw Daily Log Pattern)
 // ============================================================================
 export { DailyLogger } from './daily-log.js';

package/dist/learning/metrics-tracker.d.ts

@@ -10,8 +10,10 @@
  * - Domain coverage metrics
  * - Daily snapshots for trend analysis
  * - Dashboard data generation
+ * - Regret tracking integration (Task 2.4)
  */
 import type { QEDomain } from './qe-patterns.js';
+import type { DomainHealthSummary } from './regret-tracker.js';
 /**
  * Learning metrics snapshot
  */
@@ -66,6 +68,8 @@ export interface DashboardData {
         domain: QEDomain;
         count: number;
     }>;
+    /** Per-domain learning health from regret tracking (Task 2.4, optional) */
+    regretHealth?: DomainHealthSummary[];
 }
 /**
  * Learning Metrics Tracker
@@ -121,6 +125,13 @@ export declare class LearningMetricsTracker {
      * Save a daily metrics snapshot
      */
     saveSnapshot(): Promise<void>;
+    /**
+     * Get dashboard data enriched with regret health information.
+     *
+     * @param regretHealth - Optional per-domain regret health summaries from RegretTracker
+     * @returns Dashboard data with regret health attached
+     */
+    getDashboardDataWithRegret(regretHealth?: DomainHealthSummary[]): Promise<DashboardData>;
     /**
      * Close the database connection
      */

package/dist/learning/metrics-tracker.js

@@ -10,6 +10,7 @@
  * - Domain coverage metrics
  * - Daily snapshots for trend analysis
  * - Dashboard data generation
+ * - Regret tracking integration (Task 2.4)
  */
 import { openDatabase } from '../shared/safe-db.js';
 import path from 'node:path';
@@ -379,6 +380,19 @@ export class LearningMetricsTracker {
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(today, metrics.totalPatterns, metrics.patternsCreatedToday, metrics.totalExperiences, metrics.experiencesToday, metrics.totalQValues, metrics.avgReward, metrics.avgConfidence, metrics.avgQualityScore, metrics.successRate, metrics.patternReuseCount, metrics.shortTermPatterns, metrics.longTermPatterns, JSON.stringify(metrics.domainCoverage));
     }
+    /**
+     * Get dashboard data enriched with regret health information.
+     *
+     * @param regretHealth - Optional per-domain regret health summaries from RegretTracker
+     * @returns Dashboard data with regret health attached
+     */
+    async getDashboardDataWithRegret(regretHealth) {
+        const data = await this.getDashboardData();
+        if (regretHealth && regretHealth.length > 0) {
+            data.regretHealth = regretHealth;
+        }
+        return data;
+    }
     /**
      * Close the database connection
      */

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

@@ -12,6 +12,7 @@ import type { Database as DatabaseType } from 'better-sqlite3';
 import { type QEDomain, type QEPatternType } from './qe-patterns.js';
 import { AsymmetricLearningEngine, type AsymmetricLearningConfig } from './asymmetric-learning.js';
 import type { WitnessChain } from '../audit/witness-chain.js';
+import type { TemporalCompressionService, CompressedVector } from '../integrations/ruvector/temporal-compression.js';
 /**
  * Pattern lifecycle configuration
  */
@@ -120,6 +121,9 @@ export declare class PatternLifecycleManager {
     /** Optional witness chain for audit trail of lifecycle events (ADR-070) */
     private _witnessChain;
     set witnessChain(wc: WitnessChain | null);
+    /** Optional temporal compression service for embedding compression (ADR-085) */
+    private _compressionService;
+    set compressionService(svc: TemporalCompressionService | null);
     constructor(db: DatabaseType, config?: Partial<PatternLifecycleConfig>);
     /**
      * Ensure required schema extensions exist
@@ -224,6 +228,31 @@ export declare class PatternLifecycleManager {
      * Get the asymmetric learning engine for external use (ADR-061)
      */
     getAsymmetricEngine(): AsymmetricLearningEngine;
+    /**
+     * Compress a pattern's embedding based on its access recency (ADR-085).
+     *
+     * Only operates when the temporal compression feature flag is enabled
+     * and a compression service has been injected. Returns null when
+     * compression is not active, allowing callers to fall back gracefully.
+     */
+    compressPatternEmbedding(patternId: string): CompressedVector | null;
+    /**
+     * Decompress a compressed embedding back to Float32Array (ADR-085).
+     *
+     * Returns null when the compression service is not available.
+     * Consumers receive a standard Float32Array transparently.
+     */
+    decompressPatternEmbedding(compressed: CompressedVector): Float32Array | null;
+    /**
+     * Sweep all active patterns and compress their embeddings (ADR-085).
+     *
+     * Intended to be called periodically (e.g., during maintenance windows)
+     * to apply tier-appropriate compression to pattern embeddings. Only
+     * operates when the feature flag is on and a compression service is set.
+     *
+     * @returns Count of patterns compressed, or 0 if compression is disabled.
+     */
+    compressAllPatternEmbeddings(): number;
     /**
      * Get pattern lifecycle statistics
      */

package/dist/learning/pattern-lifecycle.js

@@ -12,6 +12,7 @@ import { PROMOTION_THRESHOLD } from './qe-patterns.js';
 import { AsymmetricLearningEngine } from './asymmetric-learning.js';
 import { safeJsonParse } from '../shared/safe-json.js';
 import { LoggerFactory } from '../logging/index.js';
+import { isTemporalCompressionEnabled } from '../integrations/ruvector/feature-flags.js';
 const logger = LoggerFactory.create('pattern-lifecycle');
 /**
  * Default lifecycle configuration
@@ -44,6 +45,9 @@ export class PatternLifecycleManager {
     /** Optional witness chain for audit trail of lifecycle events (ADR-070) */
     _witnessChain = null;
     set witnessChain(wc) { this._witnessChain = wc; }
+    /** Optional temporal compression service for embedding compression (ADR-085) */
+    _compressionService = null;
+    set compressionService(svc) { this._compressionService = svc; }
     constructor(db, config = {}) {
         this.db = db;
         this.config = { ...DEFAULT_LIFECYCLE_CONFIG, ...config };
@@ -634,6 +638,76 @@ Pattern extracted from ${exp.count} successful experiences.`;
         return this.asymmetricEngine;
     }
     // ============================================================================
+    // ADR-085: Temporal Tensor Compression
+    // ============================================================================
+    /**
+     * Compress a pattern's embedding based on its access recency (ADR-085).
+     *
+     * Only operates when the temporal compression feature flag is enabled
+     * and a compression service has been injected. Returns null when
+     * compression is not active, allowing callers to fall back gracefully.
+     */
+    compressPatternEmbedding(patternId) {
+        if (!isTemporalCompressionEnabled() || !this._compressionService) {
+            return null;
+        }
+        const pattern = this.getPattern(patternId);
+        if (!pattern || !pattern.embedding || pattern.embedding.length === 0) {
+            return null;
+        }
+        const lastAccess = pattern.lastUsedAt ?? pattern.createdAt;
+        const tier = this._compressionService.classifyTier(lastAccess);
+        const vector = new Float32Array(pattern.embedding);
+        const compressed = this._compressionService.compress(vector, tier);
+        logger.debug('Compressed pattern embedding', {
+            patternId,
+            tier,
+            ratio: (compressed.originalByteSize / compressed.compressedByteSize).toFixed(1),
+        });
+        return compressed;
+    }
+    /**
+     * Decompress a compressed embedding back to Float32Array (ADR-085).
+     *
+     * Returns null when the compression service is not available.
+     * Consumers receive a standard Float32Array transparently.
+     */
+    decompressPatternEmbedding(compressed) {
+        if (!this._compressionService) {
+            return null;
+        }
+        return this._compressionService.decompress(compressed);
+    }
+    /**
+     * Sweep all active patterns and compress their embeddings (ADR-085).
+     *
+     * Intended to be called periodically (e.g., during maintenance windows)
+     * to apply tier-appropriate compression to pattern embeddings. Only
+     * operates when the feature flag is on and a compression service is set.
+     *
+     * @returns Count of patterns compressed, or 0 if compression is disabled.
+     */
+    compressAllPatternEmbeddings() {
+        if (!isTemporalCompressionEnabled() || !this._compressionService) {
+            return 0;
+        }
+        const patterns = this.db.prepare(`
+      SELECT id FROM qe_patterns
+      WHERE deprecated_at IS NULL
+    `).all();
+        let compressed = 0;
+        for (const { id } of patterns) {
+            const result = this.compressPatternEmbedding(id);
+            if (result)
+                compressed++;
+        }
+        logger.info('Bulk pattern embedding compression complete', {
+            total: patterns.length,
+            compressed,
+        });
+        return compressed;
+    }
+    // ============================================================================
     // Statistics
     // ============================================================================
     /**

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

@@ -8,6 +8,7 @@
 import type { MemoryBackend } from '../kernel/interfaces.js';
 import type { Result } from '../shared/types/index.js';
 import { QEPattern, QEPatternContext, QEPatternType, QEDomain, CreateQEPatternOptions } from './qe-patterns.js';
+import type { FilterExpression } from '../integrations/ruvector/interfaces.js';
 /**
  * Token tracking configuration (ADR-042)
  */
@@ -122,6 +123,13 @@ export interface PatternSearchOptions {
     context?: Partial<QEPatternContext>;
     /** Include vector similarity search */
     useVectorSearch?: boolean;
+    /**
+     * Composable metadata filter expression (Task 1.2: ruvector-filter).
+     * Applied post-search to refine results by domain, severity,
+     * confidence range, tags, date range, etc.
+     * When undefined, no additional filtering is applied (backward compatible).
+     */
+    filter?: FilterExpression;
 }
 /**
  * Pattern search result with reuse optimization (ADR-042)

package/dist/learning/pattern-store.js

@@ -9,6 +9,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { ok, err } from '../shared/types/index.js';
 import { toErrorMessage, toError } from '../shared/error-utils.js';
 import { calculateQualityScore, shouldPromotePattern, validateQEPattern, mapQEDomainToAQE, PROMOTION_THRESHOLD, } from './qe-patterns.js';
+import { applyFilterSync } from '../integrations/ruvector/filter-adapter.js';
 /**
  * Default pattern store configuration
  */
@@ -514,9 +515,14 @@ export class PatternStore {
                 // while penalizing stale patterns (decayFactor is 0-1)
                 result.score = result.score * (0.7 + 0.3 * effectiveDecay);
             }
-            // Sort by score and limit
+            // Sort by score
             results.sort((a, b) => b.score - a.score);
-            const finalResults = results.slice(0, limit);
+            // Apply metadata filter BEFORE limit so we don't lose matching results (W-3 fix)
+            let filteredResults = results;
+            if (options.filter) {
+                filteredResults = applyFilterSync(results, options.filter);
+            }
+            const finalResults = filteredResults.slice(0, limit);
             // Record stats
             const latency = performance.now() - startTime;
             this.recordSearchLatency(latency);

package/dist/learning/regret-tracker.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Agentic QE v3 - Regret Tracker
+ * Task 2.4: Regret Tracking and Learning Health Dashboard
+ *
+ * Tracks cumulative regret per domain over time to determine whether
+ * QE agents are actually learning. Uses log-log regression on the
+ * regret curve to classify growth rate:
+ *
+ * - Sublinear: R(n) ~ n^alpha where alpha < 1 (learning is happening)
+ * - Linear:    R(n) ~ n (stagnation, needs intervention)
+ * - Superlinear: R(n) ~ n^alpha where alpha > 1 (getting worse)
+ *
+ * @module learning/regret-tracker
+ */
+/** A single point on the regret curve */
+export interface RegretPoint {
+    /** Number of decisions made so far */
+    decisionCount: number;
+    /** Cumulative regret at this point */
+    cumulativeRegret: number;
+    /** Timestamp when this decision was recorded */
+    timestamp: number;
+}
+/** Growth rate classification for a domain's regret curve */
+export type GrowthRate = 'sublinear' | 'linear' | 'superlinear' | 'insufficient_data';
+/** Health summary for a single domain */
+export interface DomainHealthSummary {
+    /** Domain identifier */
+    domain: string;
+    /** Total number of decisions recorded */
+    totalDecisions: number;
+    /** Current cumulative regret */
+    cumulativeRegret: number;
+    /** Growth rate classification */
+    growthRate: GrowthRate;
+    /** Whether stagnation has been detected */
+    stagnating: boolean;
+    /** Log-log slope (undefined if insufficient data) */
+    slope: number | undefined;
+    /** Average regret per decision (recent window) */
+    recentAvgRegret: number;
+}
+/** Alert emitted when a domain's regret growth rate changes */
+export interface RegretAlert {
+    /** Domain that triggered the alert */
+    domain: string;
+    /** Previous growth rate */
+    previousRate: GrowthRate;
+    /** New growth rate */
+    newRate: GrowthRate;
+    /** Timestamp of the alert */
+    timestamp: number;
+    /** Human-readable message */
+    message: string;
+}
+/** Callback for regret alerts */
+export type RegretAlertCallback = (alert: RegretAlert) => void;
+/**
+ * Compute the slope of a simple linear regression (y = mx + b).
+ *
+ * Uses the ordinary least squares formula:
+ *   m = (n * sum(xy) - sum(x) * sum(y)) / (n * sum(x^2) - (sum(x))^2)
+ *
+ * @param xs - Independent variable values
+ * @param ys - Dependent variable values
+ * @returns Slope of the regression line
+ */
+export declare function linearRegressionSlope(xs: number[], ys: number[]): number;
+/**
+ * Tracks cumulative regret per domain to assess whether QE agents
+ * are learning over time. Regret_i = optimal_reward - actual_reward.
+ * R(n) = sum of regret_i for i=1..n. Sublinear R(n) ~ n^alpha (alpha < 1)
+ * indicates learning; linear or superlinear indicates stagnation.
+ */
+export declare class RegretTracker {
+    /** Per-domain regret tracking state */
+    private domains;
+    /** Alert callbacks */
+    private alertCallbacks;
+    /** Historical alerts for review */
+    private alerts;
+    /** Maximum number of alerts to retain */
+    private readonly maxAlerts;
+    /** Window size for recent average regret calculation */
+    private readonly recentWindow;
+    constructor(options?: {
+        maxAlerts?: number;
+        recentWindow?: number;
+    });
+    /**
+     * Record a decision outcome for regret tracking.
+     *
+     * @param domain - The QE domain (e.g. 'test-generation', 'coverage-analysis')
+     * @param reward - The actual reward received (0 to 1)
+     * @param optimalReward - The best possible reward (0 to 1)
+     */
+    recordDecision(domain: string, reward: number, optimalReward: number): void;
+    /**
+     * Get the current cumulative regret for a domain.
+     *
+     * @param domain - Domain identifier
+     * @returns Cumulative regret, or 0 if domain not tracked
+     */
+    getCumulativeRegret(domain: string): number;
+    /**
+     * Get the full regret curve for a domain.
+     *
+     * @param domain - Domain identifier
+     * @returns Array of regret data points, or empty array if not tracked
+     */
+    getRegretCurve(domain: string): RegretPoint[];
+    /**
+     * Classify the growth rate of cumulative regret for a domain.
+     *
+     * Uses log-log linear regression: if R(n) ~ n^alpha, then
+     * log(R) ~ alpha * log(n), so the slope of log(R) vs log(n)
+     * gives us alpha.
+     *
+     * @param domain - Domain identifier
+     * @returns Growth rate classification
+     */
+    getRegretGrowthRate(domain: string): GrowthRate;
+    /**
+     * Detect whether a domain is stagnating (linear or superlinear regret growth).
+     *
+     * @param domain - Domain identifier
+     * @returns true if the domain shows stagnation
+     */
+    detectStagnation(domain: string): boolean;
+    /**
+     * Get a health summary for all tracked domains.
+     *
+     * @returns Array of domain health summaries, sorted by domain name
+     */
+    getHealthSummary(): DomainHealthSummary[];
+    /**
+     * Register a callback for regret growth rate transition alerts.
+     *
+     * @param callback - Function to call when a growth rate transition occurs
+     */
+    onAlert(callback: RegretAlertCallback): void;
+    /**
+     * Get all historical alerts.
+     *
+     * @returns Array of past alerts
+     */
+    getAlerts(): RegretAlert[];
+    /**
+     * Get list of all tracked domains.
+     */
+    getTrackedDomains(): string[];
+    /**
+     * Get the total number of decisions across all domains.
+     */
+    getTotalDecisions(): number;
+    /**
+     * Reset tracking data for a specific domain (or all domains).
+     *
+     * @param domain - Domain to reset, or undefined to reset all
+     */
+    reset(domain?: string): void;
+    /**
+     * Get or create domain tracking state.
+     */
+    private getOrCreateDomainState;
+    /**
+     * Classify the growth rate of a regret curve using log-log regression.
+     *
+     * @param points - Regret data points
+     * @returns Growth rate classification
+     */
+    private classifyGrowthRate;
+    /**
+     * Compute the slope of log(regret) vs log(n) for the regret curve.
+     *
+     * Filters out points where cumulative regret is zero (log(0) is undefined).
+     *
+     * @param points - Regret data points
+     * @returns Slope value, or undefined if insufficient valid data
+     */
+    private computeLogLogSlope;
+    /**
+     * Compute the average per-decision regret over the recent window.
+     */
+    private computeRecentAvgRegret;
+    /**
+     * Emit a growth rate transition alert.
+     */
+    private emitAlert;
+}
+/**
+ * Create a new RegretTracker instance.
+ *
+ * @param options - Optional configuration
+ * @returns New RegretTracker
+ */
+export declare function createRegretTracker(options?: {
+    maxAlerts?: number;
+    recentWindow?: number;
+}): RegretTracker;
+//# sourceMappingURL=regret-tracker.d.ts.map