agentic-qe 3.7.21 → 3.8.0

package/dist/integrations/ruvector/transfer-coherence-stub.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Transfer Coherence Gate Stub (Task 2.3)
+ *
+ * Provides a pass-through coherence gate for cross-domain transfer validation.
+ * When the `useCoherenceGate` feature flag is enabled, the factory function
+ * returns the real CoherenceGate (backed by prime-radiant-advanced-wasm).
+ * Otherwise, returns the pass-through stub.
+ *
+ * The interface is stable and must not change when the real implementation
+ * is swapped in.
+ *
+ * @module integrations/ruvector/transfer-coherence-stub
+ */
+/**
+ * Coherence validation result for a cross-domain transfer.
+ */
+export interface CoherenceValidation {
+    /** Whether the transfer is approved by the coherence gate */
+    approved: boolean;
+    /** Coherence energy score (lower = more coherent). Undefined when stub is used. */
+    energy?: number;
+    /** Reason for rejection (only set when approved is false) */
+    rejectionReason?: string;
+}
+/**
+ * Interface for the transfer coherence gate.
+ *
+ * Validates that a pattern transfer between domains does not introduce
+ * contradictions or reduce overall system coherence. The gate evaluates
+ * the energy landscape of the target domain with the proposed pattern
+ * and rejects transfers that would destabilize learned knowledge.
+ */
+export interface ITransferCoherenceGate {
+    /**
+     * Validate whether a pattern can be transferred to a target domain
+     * without introducing coherence violations.
+     *
+     * @param pattern - The pattern to transfer (any pattern-like object with domain info)
+     * @param targetDomain - The domain to transfer the pattern into
+     * @returns Validation result with approval status and optional energy score
+     */
+    validateTransfer(pattern: {
+        id?: string;
+        domain?: string;
+        confidence?: number;
+        [key: string]: unknown;
+    }, targetDomain: string): CoherenceValidation;
+}
+/**
+ * Stub coherence gate that always approves transfers.
+ *
+ * This is a pass-through implementation used until the real coherence gate
+ * (ADR-083) is implemented in Task 3.1. It serves as a placeholder to
+ * keep the transfer pipeline functional while the coherence system is
+ * being developed.
+ */
+export declare class TransferCoherenceStub implements ITransferCoherenceGate {
+    /**
+     * Always approves the transfer (pass-through stub).
+     *
+     * @param _pattern - Ignored in stub
+     * @param _targetDomain - Ignored in stub
+     * @returns Always returns { approved: true }
+     */
+    validateTransfer(_pattern: {
+        id?: string;
+        domain?: string;
+        confidence?: number;
+        [key: string]: unknown;
+    }, _targetDomain: string): CoherenceValidation;
+}
+/**
+ * Create a transfer coherence gate.
+ *
+ * When the `useCoherenceGate` feature flag is enabled, returns the real
+ * CoherenceGate backed by sheaf cohomology energy computation.
+ * Otherwise returns the pass-through stub.
+ */
+export declare function createTransferCoherenceGate(): ITransferCoherenceGate;
+//# sourceMappingURL=transfer-coherence-stub.d.ts.map

package/dist/integrations/ruvector/transfer-coherence-stub.js

@@ -0,0 +1,63 @@
+/**
+ * Transfer Coherence Gate Stub (Task 2.3)
+ *
+ * Provides a pass-through coherence gate for cross-domain transfer validation.
+ * When the `useCoherenceGate` feature flag is enabled, the factory function
+ * returns the real CoherenceGate (backed by prime-radiant-advanced-wasm).
+ * Otherwise, returns the pass-through stub.
+ *
+ * The interface is stable and must not change when the real implementation
+ * is swapped in.
+ *
+ * @module integrations/ruvector/transfer-coherence-stub
+ */
+import { createRequire } from 'module';
+import { getRuVectorFeatureFlags } from './feature-flags.js';
+const esmRequire = createRequire(import.meta.url);
+// ============================================================================
+// Stub Implementation
+// ============================================================================
+/**
+ * Stub coherence gate that always approves transfers.
+ *
+ * This is a pass-through implementation used until the real coherence gate
+ * (ADR-083) is implemented in Task 3.1. It serves as a placeholder to
+ * keep the transfer pipeline functional while the coherence system is
+ * being developed.
+ */
+export class TransferCoherenceStub {
+    /**
+     * Always approves the transfer (pass-through stub).
+     *
+     * @param _pattern - Ignored in stub
+     * @param _targetDomain - Ignored in stub
+     * @returns Always returns { approved: true }
+     */
+    validateTransfer(_pattern, _targetDomain) {
+        return { approved: true };
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a transfer coherence gate.
+ *
+ * When the `useCoherenceGate` feature flag is enabled, returns the real
+ * CoherenceGate backed by sheaf cohomology energy computation.
+ * Otherwise returns the pass-through stub.
+ */
+export function createTransferCoherenceGate() {
+    if (getRuVectorFeatureFlags().useCoherenceGate) {
+        try {
+            // Dynamic require to avoid circular dependency at module level
+            const { CoherenceGate } = esmRequire('./coherence-gate.js');
+            return new CoherenceGate();
+        }
+        catch {
+            // Fall through to stub if CoherenceGate fails to load
+        }
+    }
+    return new TransferCoherenceStub();
+}
+//# sourceMappingURL=transfer-coherence-stub.js.map

package/dist/integrations/ruvector/transfer-verification.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Transfer Verification (Task 2.3)
+ *
+ * Verifies that cross-domain pattern transfers do not cause regression
+ * in either the source or target domain. A transfer is considered valid
+ * only when:
+ *   1. The target domain improves (or at least does not degrade)
+ *   2. The source domain does not regress
+ *
+ * This double-gate ensures that knowledge sharing is always net-positive.
+ *
+ * @module integrations/ruvector/transfer-verification
+ */
+/**
+ * Performance snapshot for a domain at a point in time.
+ */
+export interface DomainPerformanceSnapshot {
+    /** Domain identifier */
+    domain: string;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Average confidence of patterns in the domain */
+    avgConfidence: number;
+    /** Number of patterns in the domain */
+    patternCount: number;
+    /** Timestamp of the snapshot */
+    timestamp: number;
+}
+/**
+ * Transfer result to be verified.
+ */
+export interface TransferResultForVerification {
+    /** Unique transfer identifier */
+    transferId: string;
+    /** Source domain */
+    sourceDomain: string;
+    /** Target domain */
+    targetDomain: string;
+    /** Source domain performance BEFORE the transfer */
+    sourcePerformanceBefore: DomainPerformanceSnapshot;
+    /** Source domain performance AFTER the transfer */
+    sourcePerformanceAfter: DomainPerformanceSnapshot;
+    /** Target domain performance BEFORE the transfer */
+    targetPerformanceBefore: DomainPerformanceSnapshot;
+    /** Target domain performance AFTER the transfer */
+    targetPerformanceAfter: DomainPerformanceSnapshot;
+}
+/**
+ * Result of the transfer verification.
+ */
+export interface VerificationResult {
+    /** Whether the transfer passed verification */
+    passed: boolean;
+    /** Whether the source domain maintained performance */
+    sourceStable: boolean;
+    /** Whether the target domain improved */
+    targetImproved: boolean;
+    /** Change in source domain success rate */
+    sourceDelta: number;
+    /** Change in target domain success rate */
+    targetDelta: number;
+    /** Change in source domain confidence */
+    sourceConfidenceDelta: number;
+    /** Change in target domain confidence */
+    targetConfidenceDelta: number;
+    /** Failure reason (when passed is false) */
+    failureReason?: string;
+}
+/**
+ * Configuration for transfer verification thresholds.
+ */
+export interface TransferVerificationConfig {
+    /**
+     * Maximum allowed regression in source domain success rate.
+     * A small tolerance is permitted to account for noise.
+     * @default 0.05 (5%)
+     */
+    maxSourceRegression: number;
+    /**
+     * Minimum required improvement in target domain success rate.
+     * Set to 0 to allow neutral transfers (no improvement but no regression).
+     * @default 0.0
+     */
+    minTargetImprovement: number;
+    /**
+     * Maximum allowed regression in source domain confidence.
+     * @default 0.1
+     */
+    maxSourceConfidenceRegression: number;
+}
+/** Default verification configuration */
+export declare const DEFAULT_VERIFICATION_CONFIG: TransferVerificationConfig;
+/**
+ * Verifies cross-domain transfers to prevent regression.
+ *
+ * The verifier applies a double-gate:
+ *   Gate 1 (Source Stability): Source domain must not regress beyond tolerance
+ *   Gate 2 (Target Improvement): Target domain must improve or stay neutral
+ *
+ * Both gates must pass for the transfer to be approved.
+ */
+export declare class TransferVerifier {
+    private readonly config;
+    constructor(config?: Partial<TransferVerificationConfig>);
+    /**
+     * Verify that a transfer did not cause regression in either domain.
+     *
+     * @param result - The transfer result containing before/after performance data
+     * @returns Verification result with pass/fail and detailed deltas
+     */
+    verifyTransfer(result: TransferResultForVerification): VerificationResult;
+    /** Get the current verification configuration */
+    getConfig(): TransferVerificationConfig;
+}
+/**
+ * Create a transfer verifier with the given configuration.
+ */
+export declare function createTransferVerifier(config?: Partial<TransferVerificationConfig>): TransferVerifier;
+//# sourceMappingURL=transfer-verification.d.ts.map

package/dist/integrations/ruvector/transfer-verification.js

@@ -0,0 +1,115 @@
+/**
+ * Transfer Verification (Task 2.3)
+ *
+ * Verifies that cross-domain pattern transfers do not cause regression
+ * in either the source or target domain. A transfer is considered valid
+ * only when:
+ *   1. The target domain improves (or at least does not degrade)
+ *   2. The source domain does not regress
+ *
+ * This double-gate ensures that knowledge sharing is always net-positive.
+ *
+ * @module integrations/ruvector/transfer-verification
+ */
+import { LoggerFactory } from '../../logging/index.js';
+const logger = LoggerFactory.create('transfer-verification');
+/** Default verification configuration */
+export const DEFAULT_VERIFICATION_CONFIG = {
+    maxSourceRegression: 0.05,
+    minTargetImprovement: 0.0,
+    maxSourceConfidenceRegression: 0.1,
+};
+// ============================================================================
+// Transfer Verifier
+// ============================================================================
+/**
+ * Verifies cross-domain transfers to prevent regression.
+ *
+ * The verifier applies a double-gate:
+ *   Gate 1 (Source Stability): Source domain must not regress beyond tolerance
+ *   Gate 2 (Target Improvement): Target domain must improve or stay neutral
+ *
+ * Both gates must pass for the transfer to be approved.
+ */
+export class TransferVerifier {
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_VERIFICATION_CONFIG, ...config };
+    }
+    /**
+     * Verify that a transfer did not cause regression in either domain.
+     *
+     * @param result - The transfer result containing before/after performance data
+     * @returns Verification result with pass/fail and detailed deltas
+     */
+    verifyTransfer(result) {
+        const sourceDelta = result.sourcePerformanceAfter.successRate -
+            result.sourcePerformanceBefore.successRate;
+        const targetDelta = result.targetPerformanceAfter.successRate -
+            result.targetPerformanceBefore.successRate;
+        const sourceConfidenceDelta = result.sourcePerformanceAfter.avgConfidence -
+            result.sourcePerformanceBefore.avgConfidence;
+        const targetConfidenceDelta = result.targetPerformanceAfter.avgConfidence -
+            result.targetPerformanceBefore.avgConfidence;
+        // Gate 1: Source domain must not regress beyond tolerance
+        const sourceStable = sourceDelta >= -this.config.maxSourceRegression &&
+            sourceConfidenceDelta >= -this.config.maxSourceConfidenceRegression;
+        // Gate 2: Target domain must improve (or at least not degrade)
+        const targetImproved = targetDelta >= this.config.minTargetImprovement;
+        // Both gates must pass
+        const passed = sourceStable && targetImproved;
+        let failureReason;
+        if (!passed) {
+            const reasons = [];
+            if (!sourceStable) {
+                reasons.push(`source domain regressed: successRate delta=${sourceDelta.toFixed(4)}, ` +
+                    `confidence delta=${sourceConfidenceDelta.toFixed(4)}`);
+            }
+            if (!targetImproved) {
+                reasons.push(`target domain did not improve: successRate delta=${targetDelta.toFixed(4)}`);
+            }
+            failureReason = reasons.join('; ');
+        }
+        if (!passed) {
+            logger.warn('Transfer verification failed', {
+                transferId: result.transferId,
+                sourceDomain: result.sourceDomain,
+                targetDomain: result.targetDomain,
+                sourceDelta,
+                targetDelta,
+                failureReason,
+            });
+        }
+        else {
+            logger.debug('Transfer verification passed', {
+                transferId: result.transferId,
+                sourceDelta,
+                targetDelta,
+            });
+        }
+        return {
+            passed,
+            sourceStable,
+            targetImproved,
+            sourceDelta,
+            targetDelta,
+            sourceConfidenceDelta,
+            targetConfidenceDelta,
+            failureReason,
+        };
+    }
+    /** Get the current verification configuration */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a transfer verifier with the given configuration.
+ */
+export function createTransferVerifier(config) {
+    return new TransferVerifier(config);
+}
+//# sourceMappingURL=transfer-verification.js.map

package/dist/kernel/hnsw-adapter.d.ts

@@ -10,12 +10,14 @@
  * @module kernel/hnsw-adapter
  */
 import type { IHnswIndexProvider, SearchResult, HnswConfig } from './hnsw-index-provider.js';
+import type { HnswHealthMonitor, HnswHealthReport } from '../integrations/ruvector/hnsw-health-monitor.js';
 /**
  * Well-known index names used across the AQE platform.
  */
 export type HnswIndexName = 'patterns' | 'qe-memory' | 'learning' | 'coverage';
 /**
- * Adapter that wraps ProgressiveHnswBackend and provides backward-compatible
+ * Adapter that wraps ProgressiveHnswBackend (or NativeHnswBackend when
+ * the useNativeHNSW feature flag is enabled) and provides backward-compatible
  * APIs matching the old InMemoryHNSWIndex and RuvectorFlatIndex interfaces.
  *
  * This adapter bridges the gap between the new IHnswIndexProvider interface
@@ -23,11 +25,18 @@ export type HnswIndexName = 'patterns' | 'qe-memory' | 'learning' | 'coverage';
  */
 export declare class HnswAdapter implements IHnswIndexProvider {
     private readonly backend;
+    private readonly _isNativeBackend;
     private readonly indexName;
     /** Maps string keys to numeric IDs (for backward compat with old APIs) */
     private stringToNumericId;
     private numericToStringId;
     private nextAutoId;
+    /** Health monitor (lazily created when feature flag is enabled) */
+    private healthMonitor;
+    private healthMonitorLoaded;
+    private operationsSinceLastCheck;
+    private healthCheckFrequency;
+    private lastHealthReport;
     constructor(name: string, config?: Partial<HnswConfig>);
     add(id: number, vector: Float32Array, metadata?: Record<string, unknown>): void;
     search(query: Float32Array, k: number): SearchResult[];
@@ -68,10 +77,52 @@ export declare class HnswAdapter implements IHnswIndexProvider {
      * Check whether @ruvector/gnn is available.
      */
     isRuvectorAvailable(): boolean;
+    /**
+     * Check whether this adapter is using the native HNSW backend.
+     */
+    isNativeBackend(): boolean;
     /**
      * Get the index name.
      */
     getName(): string;
+    /**
+     * Set the health check frequency (number of operations between checks).
+     * Only applies when the useHnswHealthMonitor feature flag is enabled.
+     *
+     * @param frequency - Number of add/remove operations between health checks
+     */
+    setHealthCheckFrequency(frequency: number): void;
+    /**
+     * Get the health check frequency.
+     */
+    getHealthCheckFrequency(): number;
+    /**
+     * Get the last health report, or null if no check has run.
+     */
+    getLastHealthReport(): HnswHealthReport | null;
+    /**
+     * Get the health monitor instance, or null if not enabled.
+     */
+    getHealthMonitor(): HnswHealthMonitor | null;
+    /**
+     * Conditionally run a health check based on operation count and feature flag.
+     * Non-blocking: runs asynchronously to avoid slowing operations.
+     */
+    private maybeRunHealthCheck;
+    /**
+     * Lazily load and create the health monitor.
+     */
+    private ensureHealthMonitor;
+    /**
+     * Create the appropriate HNSW backend based on feature flags.
+     *
+     * When useNativeHNSW is enabled, tries to create a NativeHnswBackend.
+     * Falls back to ProgressiveHnswBackend if the native binary is unavailable.
+     *
+     * @param config - HNSW configuration
+     * @returns The backend instance and whether it is native
+     */
+    private static createBackend;
     /**
      * Create or retrieve a named HNSW index.
      *

package/dist/kernel/hnsw-adapter.js

@@ -10,6 +10,8 @@
  * @module kernel/hnsw-adapter
  */
 import { ProgressiveHnswBackend } from './progressive-hnsw-backend.js';
+import { NativeHnswBackend, NativeHnswUnavailableError } from './native-hnsw-backend.js';
+import { isNativeHNSWEnabled, isHnswHealthMonitorEnabled } from '../integrations/ruvector/feature-flags.js';
 /**
  * Default configurations for each named index.
  */
@@ -51,7 +53,8 @@ const registry = new Map();
 // HnswAdapter
 // ============================================================================
 /**
- * Adapter that wraps ProgressiveHnswBackend and provides backward-compatible
+ * Adapter that wraps ProgressiveHnswBackend (or NativeHnswBackend when
+ * the useNativeHNSW feature flag is enabled) and provides backward-compatible
  * APIs matching the old InMemoryHNSWIndex and RuvectorFlatIndex interfaces.
  *
  * This adapter bridges the gap between the new IHnswIndexProvider interface
@@ -59,21 +62,32 @@ const registry = new Map();
  */
 export class HnswAdapter {
     backend;
+    _isNativeBackend;
     indexName;
     /** Maps string keys to numeric IDs (for backward compat with old APIs) */
     stringToNumericId = new Map();
     numericToStringId = new Map();
     nextAutoId = 0;
+    /** Health monitor (lazily created when feature flag is enabled) */
+    healthMonitor = null;
+    healthMonitorLoaded = false;
+    operationsSinceLastCheck = 0;
+    healthCheckFrequency = 100;
+    lastHealthReport = null;
     constructor(name, config) {
         this.indexName = name;
         const defaults = INDEX_DEFAULTS[name] ?? {};
-        this.backend = new ProgressiveHnswBackend({ ...defaults, ...config });
+        const mergedConfig = { ...defaults, ...config };
+        const { backend, isNative } = HnswAdapter.createBackend(mergedConfig);
+        this.backend = backend;
+        this._isNativeBackend = isNative;
     }
     // ============================================================================
     // IHnswIndexProvider implementation
     // ============================================================================
     add(id, vector, metadata) {
         this.backend.add(id, vector, metadata);
+        this.maybeRunHealthCheck();
     }
     search(query, k) {
         const start = performance.now();
@@ -154,7 +168,7 @@ export class HnswAdapter {
      * Clear all vectors from the index.
      */
     clear() {
-        this.backend.clear();
+        this.backend.clear?.();
         this.stringToNumericId.clear();
         this.numericToStringId.clear();
         this.nextAutoId = 0;
@@ -163,7 +177,20 @@ export class HnswAdapter {
      * Check whether @ruvector/gnn is available.
      */
     isRuvectorAvailable() {
-        return this.backend.isRuvectorAvailable();
+        if (this.backend instanceof ProgressiveHnswBackend) {
+            return this.backend.isRuvectorAvailable();
+        }
+        // NativeHnswBackend uses @ruvector/router VectorDb
+        if (this.backend instanceof NativeHnswBackend) {
+            return this.backend.isNativeAvailable();
+        }
+        return false;
+    }
+    /**
+     * Check whether this adapter is using the native HNSW backend.
+     */
+    isNativeBackend() {
+        return this._isNativeBackend;
     }
     /**
      * Get the index name.
@@ -172,6 +199,114 @@ export class HnswAdapter {
         return this.indexName;
     }
     // ============================================================================
+    // Health Monitoring
+    // ============================================================================
+    /**
+     * Set the health check frequency (number of operations between checks).
+     * Only applies when the useHnswHealthMonitor feature flag is enabled.
+     *
+     * @param frequency - Number of add/remove operations between health checks
+     */
+    setHealthCheckFrequency(frequency) {
+        this.healthCheckFrequency = Math.max(1, frequency);
+    }
+    /**
+     * Get the health check frequency.
+     */
+    getHealthCheckFrequency() {
+        return this.healthCheckFrequency;
+    }
+    /**
+     * Get the last health report, or null if no check has run.
+     */
+    getLastHealthReport() {
+        return this.lastHealthReport;
+    }
+    /**
+     * Get the health monitor instance, or null if not enabled.
+     */
+    getHealthMonitor() {
+        return this.healthMonitor;
+    }
+    /**
+     * Conditionally run a health check based on operation count and feature flag.
+     * Non-blocking: runs asynchronously to avoid slowing operations.
+     */
+    maybeRunHealthCheck() {
+        if (!isHnswHealthMonitorEnabled())
+            return;
+        this.operationsSinceLastCheck++;
+        if (this.operationsSinceLastCheck < this.healthCheckFrequency)
+            return;
+        this.operationsSinceLastCheck = 0;
+        this.ensureHealthMonitor();
+        if (this.healthMonitor) {
+            try {
+                this.lastHealthReport = this.healthMonitor.checkHealth(this.backend);
+                if (!this.lastHealthReport.healthy) {
+                    console.warn(`[HNSW-Health] Index "${this.indexName}" health check failed: ` +
+                        `${this.lastHealthReport.alerts.length} alert(s). ` +
+                        `Coherence: ${this.lastHealthReport.metrics.coherenceScore.toFixed(3)}`);
+                }
+            }
+            catch (err) {
+                // Health checks must never break normal operations
+                console.warn(`[HNSW-Health] Health check error for "${this.indexName}":`, err);
+            }
+        }
+    }
+    /**
+     * Lazily load and create the health monitor.
+     */
+    ensureHealthMonitor() {
+        if (this.healthMonitorLoaded)
+            return;
+        this.healthMonitorLoaded = true;
+        try {
+            // Dynamic import to avoid circular dependencies and keep startup fast
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const mod = require('../integrations/ruvector/hnsw-health-monitor.js');
+            this.healthMonitor = mod.createHnswHealthMonitor();
+        }
+        catch (err) {
+            // Module not available, health monitoring disabled
+            if (process.env.DEBUG)
+                console.debug('[HNSW-Health] Monitor module unavailable:', err instanceof Error ? err.message : err);
+            this.healthMonitor = null;
+        }
+    }
+    // ============================================================================
+    // Backend Selection
+    // ============================================================================
+    /**
+     * Create the appropriate HNSW backend based on feature flags.
+     *
+     * When useNativeHNSW is enabled, tries to create a NativeHnswBackend.
+     * Falls back to ProgressiveHnswBackend if the native binary is unavailable.
+     *
+     * @param config - HNSW configuration
+     * @returns The backend instance and whether it is native
+     */
+    static createBackend(config) {
+        if (isNativeHNSWEnabled()) {
+            try {
+                const native = new NativeHnswBackend(config);
+                return { backend: native, isNative: true };
+            }
+            catch (err) {
+                if (err instanceof NativeHnswUnavailableError) {
+                    // Expected: native binary not available, fall back silently
+                    console.info(`[HNSW] Native backend unavailable, falling back to JS: ${err.message}`);
+                }
+                else {
+                    // Unexpected error, log warning and fall back
+                    console.warn(`[HNSW] Unexpected error creating native backend, falling back to JS:`, err);
+                }
+            }
+        }
+        return { backend: new ProgressiveHnswBackend(config), isNative: false };
+    }
+    // ============================================================================
     // Factory
     // ============================================================================
     /**

package/dist/kernel/hnsw-index-provider.d.ts

@@ -86,5 +86,10 @@ export interface IHnswIndexProvider {
      * For approximate HNSW this returns an estimate based on configuration.
      */
     recall(): number;
+    /**
+     * Clear all vectors from the index.
+     * Optional: implementations that don't support clearing can omit this.
+     */
+    clear?(): void;
 }
 //# sourceMappingURL=hnsw-index-provider.d.ts.map