agentic-qe 3.9.0 → 3.9.2

package/dist/integrations/ruvector/cognitive-routing.js

@@ -0,0 +1,208 @@
+/**
+ * R13: Cognitive Routing — Predictive Coding for Agent Communication
+ *
+ * Bandwidth reduction via sliding-window prediction + delta-only transmission.
+ * Oscillatory routing multiplexes concurrent message streams round-robin.
+ * TypeScript-only; no external dependencies.
+ *
+ * @module integrations/ruvector/cognitive-routing
+ */
+import { getRuVectorFeatureFlags } from './feature-flags.js';
+const DEFAULT_CONFIG = {
+    predictionWindowSize: 10, compressionThreshold: 0.3,
+    maxConcurrentStreams: 8, oscillationFrequencyMs: 100,
+};
+function estimateSize(value) {
+    try {
+        return JSON.stringify(value).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function computeDelta(predicted, actual) {
+    const delta = {};
+    let hasChanges = false;
+    for (const key of Object.keys(actual)) {
+        if (JSON.stringify(predicted[key]) !== JSON.stringify(actual[key])) {
+            delta[key] = actual[key];
+            hasChanges = true;
+        }
+    }
+    for (const key of Object.keys(predicted)) {
+        if (!(key in actual)) {
+            delta[key] = undefined;
+            hasChanges = true;
+        }
+    }
+    return hasChanges ? delta : null;
+}
+function applyDelta(predicted, delta) {
+    const result = { ...predicted };
+    for (const [key, value] of Object.entries(delta)) {
+        if (value === undefined)
+            delete result[key];
+        else
+            result[key] = value;
+    }
+    return result;
+}
+/** Sliding-window predictor: predicts next payload as copy of last seen. */
+export class MessagePredictor {
+    windowSize;
+    windows = new Map();
+    constructor(windowSize) { this.windowSize = Math.max(1, windowSize); }
+    predict(streamId) {
+        const w = this.windows.get(streamId);
+        if (!w || w.length === 0)
+            return null;
+        const last = w[w.length - 1];
+        if (typeof last !== 'object' || last === null || Array.isArray(last))
+            return null;
+        return { ...last };
+    }
+    record(streamId, payload) {
+        let w = this.windows.get(streamId);
+        if (!w) {
+            w = [];
+            this.windows.set(streamId, w);
+        }
+        w.push(payload);
+        if (w.length > this.windowSize)
+            w.shift();
+    }
+    removeStream(streamId) { this.windows.delete(streamId); }
+}
+/** Round-robin multiplexer for concurrent message streams. */
+export class OscillatoryRouter {
+    maxStreams;
+    cycleMs;
+    streamIds = [];
+    currentIndex = 0;
+    constructor(maxStreams, cycleMs) {
+        this.maxStreams = Math.max(1, maxStreams);
+        this.cycleMs = Math.max(1, cycleMs);
+    }
+    addStream(streamId) {
+        if (this.streamIds.includes(streamId) || this.streamIds.length >= this.maxStreams)
+            return false;
+        this.streamIds.push(streamId);
+        return true;
+    }
+    removeStream(streamId) {
+        const idx = this.streamIds.indexOf(streamId);
+        if (idx === -1)
+            return false;
+        this.streamIds.splice(idx, 1);
+        if (this.currentIndex >= this.streamIds.length)
+            this.currentIndex = 0;
+        return true;
+    }
+    nextStream() {
+        if (this.streamIds.length === 0)
+            return null;
+        const s = this.streamIds[this.currentIndex];
+        this.currentIndex = (this.currentIndex + 1) % this.streamIds.length;
+        return s;
+    }
+    getActiveStreams() { return [...this.streamIds]; }
+    get activeCount() { return this.streamIds.length; }
+}
+/** Combines MessagePredictor + OscillatoryRouter for bandwidth-efficient routing. */
+export class CognitiveRouter {
+    config;
+    predictor;
+    router;
+    lastPayloads = new Map();
+    totalMessages = 0;
+    compressedMessages = 0;
+    totalOriginalBytes = 0;
+    totalCompressedBytes = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.predictor = new MessagePredictor(this.config.predictionWindowSize);
+        this.router = new OscillatoryRouter(this.config.maxConcurrentStreams, this.config.oscillationFrequencyMs);
+    }
+    send(streamId, senderId, receiverId, payload) {
+        this.totalMessages++;
+        const originalSize = estimateSize(payload);
+        this.totalOriginalBytes += originalSize;
+        let compressed = false;
+        let transmittedPayload = payload;
+        let compressedSize = originalSize;
+        if (typeof payload === 'object' && payload !== null && !Array.isArray(payload)) {
+            const prediction = this.predictor.predict(streamId);
+            if (prediction) {
+                const delta = computeDelta(prediction, payload);
+                if (delta) {
+                    const deltaSize = estimateSize(delta);
+                    if (1 - deltaSize / Math.max(originalSize, 1) >= this.config.compressionThreshold) {
+                        transmittedPayload = { __delta: true, __changes: delta };
+                        compressedSize = estimateSize(transmittedPayload);
+                        compressed = true;
+                        this.compressedMessages++;
+                    }
+                }
+                else {
+                    transmittedPayload = { __delta: true, __changes: {} };
+                    compressedSize = estimateSize(transmittedPayload);
+                    compressed = true;
+                    this.compressedMessages++;
+                }
+            }
+        }
+        this.totalCompressedBytes += compressedSize;
+        this.predictor.record(streamId, payload);
+        this.lastPayloads.set(streamId, payload);
+        return { streamId, senderId, receiverId, payload: transmittedPayload,
+            compressed, originalSize, compressedSize, timestamp: Date.now() };
+    }
+    receive(message) {
+        if (!message.compressed || typeof message.payload !== 'object' || message.payload === null) {
+            this.lastPayloads.set(message.streamId, message.payload);
+            this.predictor.record(message.streamId, message.payload);
+            return message.payload;
+        }
+        const envelope = message.payload;
+        if (!envelope.__delta) {
+            this.lastPayloads.set(message.streamId, message.payload);
+            this.predictor.record(message.streamId, message.payload);
+            return message.payload;
+        }
+        const prediction = this.predictor.predict(message.streamId);
+        const changes = (envelope.__changes ?? {});
+        if (!prediction)
+            return changes;
+        const reconstructed = applyDelta(prediction, changes);
+        this.predictor.record(message.streamId, reconstructed);
+        this.lastPayloads.set(message.streamId, reconstructed);
+        return reconstructed;
+    }
+    getStats() {
+        const saved = this.totalOriginalBytes - this.totalCompressedBytes;
+        return {
+            totalMessages: this.totalMessages, compressedMessages: this.compressedMessages,
+            bandwidthSavedBytes: Math.max(0, saved),
+            bandwidthReductionPercent: this.totalOriginalBytes > 0
+                ? (Math.max(0, saved) / this.totalOriginalBytes) * 100 : 0,
+            activeStreams: this.router.activeCount,
+        };
+    }
+    addStream(streamId) { this.router.addStream(streamId); }
+    removeStream(streamId) {
+        this.router.removeStream(streamId);
+        this.predictor.removeStream(streamId);
+        this.lastPayloads.delete(streamId);
+    }
+}
+/** Create a CognitiveRouter if the feature flag is enabled, otherwise null. */
+export function createCognitiveRouter(config) {
+    if (!isCognitiveRoutingEnabled())
+        return null;
+    return new CognitiveRouter(config);
+}
+/** Check if Cognitive Routing feature flag is enabled. */
+export function isCognitiveRoutingEnabled() {
+    return getRuVectorFeatureFlags().useCognitiveRouting;
+}
+//# sourceMappingURL=cognitive-routing.js.map

package/dist/integrations/ruvector/feature-flags.d.ts

@@ -189,6 +189,42 @@ export interface RuVectorFeatureFlags {
      * @default true
      */
     useReasoningQEC: boolean;
+    /**
+     * Enable RVF-backed PatternStore (ADR-066)
+     * Replaces SQLite BLOB + in-memory HNSW rebuild with @ruvector/rvf-node
+     * persistent HNSW. Eliminates cold-start index rebuild, provides sub-ms
+     * search via native SIMD acceleration, and enables COW branching (ADR-067/069).
+     * Pattern metadata remains in SQLite; only vector storage moves to RVF.
+     * @default false — will flip to true after benchmarks confirm improvement
+     */
+    useRVFPatternStore: boolean;
+    /**
+     * Enable Agent Memory Branching via RVF COW (ADR-067)
+     * Each spawned agent gets a lightweight COW-derived .rvf branch file.
+     * Agent writes are isolated; successful agents merge back, failed agents
+     * discard at zero cost. Requires useRVFPatternStore to be enabled.
+     * @default false — will flip to true after benchmarks confirm improvement
+     */
+    useAgentMemoryBranching: boolean;
+    /**
+     * Enable Unified HNSW Provider (ADR-071)
+     * Routes all three legacy HNSW implementations (TypeScript, RuvectorFlatIndex,
+     * QEGNNEmbeddingIndex) through a single HnswAdapter backend. Eliminates
+     * inconsistent search results and triples maintenance burden.
+     * @default false — will flip to true after shadow validation confirms <2% divergence
+     */
+    useUnifiedHnsw: boolean;
+    /**
+     * RVF Migration Stage (ADR-072)
+     * Controls the gradual migration from SQLite to RVF primary persistence.
+     *   Stage 0: SQLite only (legacy, no RVF involvement)
+     *   Stage 1: Hybrid (current — ADR-065, RvfPatternStore for vectors, SQLite for metadata)
+     *   Stage 2: Dual-write, SQLite source of truth (both engines receive writes, reads from SQLite)
+     *   Stage 3: Dual-write, RVF source of truth (both engines receive writes, reads from RVF)
+     *   Stage 4: RVF primary, SQLite escape hatch (writes to RVF only, SQLite for fallback)
+     * @default 1 — current hybrid
+     */
+    rvfMigrationStage: 0 | 1 | 2 | 3 | 4;
     /**
      * Enable HDC Pattern Fingerprinting (R1, ADR-087)
      * Uses 10,000-bit binary hypervectors with XOR binding for O(1) compositional
@@ -301,6 +337,24 @@ export interface RuVectorFeatureFlags {
      * @default false
      */
     useGrangerCausality: boolean;
+    /**
+     * Enable Cognitive Routing (R13, ADR-087)
+     * Predictive coding for agent communication bandwidth reduction. Predicts
+     * next message from sliding window context and sends only the delta.
+     * Oscillatory routing multiplexes concurrent message streams.
+     * Consumer: agent communication layer
+     * @default false
+     */
+    useCognitiveRouting: boolean;
+    /**
+     * Enable Hyperbolic HNSW (R14, ADR-087)
+     * Poincare ball embeddings for hierarchical data. Maps tree-structured data
+     * (module hierarchies, test suite trees) into hyperbolic space where distances
+     * naturally preserve parent-child relationships.
+     * Consumer: code-intelligence hierarchical search
+     * @default false
+     */
+    useHyperbolicHnsw: boolean;
 }
 /**
  * Default feature flags - all enabled by default
@@ -453,6 +507,26 @@ export declare function isCoherenceActionGateEnabled(): boolean;
  * @returns true if useReasoningQEC flag is set
  */
 export declare function isReasoningQECEnabled(): boolean;
+/**
+ * Check if RVF-backed PatternStore is enabled (ADR-066)
+ * @returns true if useRVFPatternStore flag is set
+ */
+export declare function isRVFPatternStoreEnabled(): boolean;
+/**
+ * Check if Agent Memory Branching is enabled (ADR-067)
+ * @returns true if useAgentMemoryBranching flag is set
+ */
+export declare function isAgentMemoryBranchingEnabled(): boolean;
+/**
+ * Check if Unified HNSW Provider is enabled (ADR-071)
+ * @returns true if useUnifiedHnsw flag is set
+ */
+export declare function isUnifiedHnswEnabled(): boolean;
+/**
+ * Get the current RVF migration stage (ADR-072)
+ * @returns 0-4 representing the migration stage
+ */
+export declare function getRvfMigrationStage(): 0 | 1 | 2 | 3 | 4;
 /**
  * Check if HDC Pattern Fingerprinting is enabled (R1, ADR-087)
  * @returns true if useHDCFingerprinting flag is set
@@ -518,6 +592,16 @@ export declare function isEpropOnlineLearningEnabled(): boolean;
  * @returns true if useGrangerCausality flag is set
  */
 export declare function isGrangerCausalityEnabled(): boolean;
+/**
+ * Check if Cognitive Routing is enabled (R13, ADR-087)
+ * @returns true if useCognitiveRouting flag is set
+ */
+export declare function isCognitiveRoutingEnabled(): boolean;
+/**
+ * Check if Hyperbolic HNSW is enabled (R14, ADR-087)
+ * @returns true if useHyperbolicHnsw flag is set
+ */
+export declare function isHyperbolicHnswEnabled(): boolean;
 /**
  * Initialize feature flags from environment variables
  *

package/dist/integrations/ruvector/feature-flags.js

@@ -36,6 +36,11 @@ const DEFAULT_FEATURE_FLAGS = {
     useDAGAttention: true,
     useCoherenceActionGate: true,
     useReasoningQEC: true,
+    // RVF Cluster (ADR-065–072)
+    useRVFPatternStore: true, // benchmarked: 0.4ms cold-start, 0.5ms search p50
+    useAgentMemoryBranching: true, // COW derive + ingest-log merge, wired into kernel boot (ADR-067)
+    useUnifiedHnsw: true, // HnswLegacyBridge routes all consumers through unified backend (ADR-071)
+    rvfMigrationStage: 2, // ADR-072: dual-write (stage 2) — both engines receive writes, SQLite reads
     // Phase 5 (ADR-087) — enabled by default, opt-out
     useHDCFingerprinting: true,
     useCusumDriftDetection: true,
@@ -53,6 +58,9 @@ const DEFAULT_FEATURE_FLAGS = {
     // Phase 5 Milestone 4 (ADR-087) — verified, default true (opt-out)
     useEpropOnlineLearning: true,
     useGrangerCausality: true,
+    // Phase 5 Milestone 5 (ADR-087) — backlog/speculative, default false (opt-in)
+    useCognitiveRouting: false,
+    useHyperbolicHnsw: false,
 };
 // ============================================================================
 // Internal State
@@ -261,6 +269,35 @@ export function isCoherenceActionGateEnabled() {
 export function isReasoningQECEnabled() {
     return currentFeatureFlags.useReasoningQEC;
 }
+// RVF Cluster (ADR-065–072) convenience functions
+/**
+ * Check if RVF-backed PatternStore is enabled (ADR-066)
+ * @returns true if useRVFPatternStore flag is set
+ */
+export function isRVFPatternStoreEnabled() {
+    return currentFeatureFlags.useRVFPatternStore;
+}
+/**
+ * Check if Agent Memory Branching is enabled (ADR-067)
+ * @returns true if useAgentMemoryBranching flag is set
+ */
+export function isAgentMemoryBranchingEnabled() {
+    return currentFeatureFlags.useAgentMemoryBranching;
+}
+/**
+ * Check if Unified HNSW Provider is enabled (ADR-071)
+ * @returns true if useUnifiedHnsw flag is set
+ */
+export function isUnifiedHnswEnabled() {
+    return currentFeatureFlags.useUnifiedHnsw;
+}
+/**
+ * Get the current RVF migration stage (ADR-072)
+ * @returns 0-4 representing the migration stage
+ */
+export function getRvfMigrationStage() {
+    return currentFeatureFlags.rvfMigrationStage;
+}
 // Phase 5 (ADR-087) convenience functions
 /**
  * Check if HDC Pattern Fingerprinting is enabled (R1, ADR-087)
@@ -356,6 +393,21 @@ export function isEpropOnlineLearningEnabled() {
 export function isGrangerCausalityEnabled() {
     return currentFeatureFlags.useGrangerCausality;
 }
+// Phase 5 Milestone 5 (ADR-087) convenience functions
+/**
+ * Check if Cognitive Routing is enabled (R13, ADR-087)
+ * @returns true if useCognitiveRouting flag is set
+ */
+export function isCognitiveRoutingEnabled() {
+    return currentFeatureFlags.useCognitiveRouting;
+}
+/**
+ * Check if Hyperbolic HNSW is enabled (R14, ADR-087)
+ * @returns true if useHyperbolicHnsw flag is set
+ */
+export function isHyperbolicHnswEnabled() {
+    return currentFeatureFlags.useHyperbolicHnsw;
+}
 // ============================================================================
 // Environment Variable Support
 // ============================================================================
@@ -466,6 +518,13 @@ export function initFeatureFlagsFromEnv() {
     if (process.env.RUVECTOR_USE_GRANGER_CAUSALITY !== undefined) {
         envFlags.useGrangerCausality = process.env.RUVECTOR_USE_GRANGER_CAUSALITY === 'true';
     }
+    // Phase 5 Milestone 5 (ADR-087) env vars
+    if (process.env.RUVECTOR_USE_COGNITIVE_ROUTING !== undefined) {
+        envFlags.useCognitiveRouting = process.env.RUVECTOR_USE_COGNITIVE_ROUTING === 'true';
+    }
+    if (process.env.RUVECTOR_USE_HYPERBOLIC_HNSW !== undefined) {
+        envFlags.useHyperbolicHnsw = process.env.RUVECTOR_USE_HYPERBOLIC_HNSW === 'true';
+    }
     setRuVectorFeatureFlags(envFlags);
 }
 // ============================================================================

package/dist/integrations/ruvector/hdc-fingerprint.d.ts

@@ -44,6 +44,74 @@ export interface PatternInput {
     type: string;
     content?: string;
 }
+/**
+ * Generate a random binary hypervector using crypto-quality randomness.
+ * @param dimensions Number of bits. Default: 10000
+ */
+export declare function createRandomHypervector(dimensions?: number): Uint8Array;
+/**
+ * XOR binding — component-wise XOR of two packed-bit vectors.
+ * This is the key composition operation in HDC.
+ */
+export declare function bind(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Majority-rule bundling — creates a "superposition" of vectors.
+ * For each bit position, takes the majority value across all input vectors.
+ * Ties are broken by setting the bit to 1 (arbitrary but deterministic).
+ */
+export declare function bundle(vectors: Uint8Array[]): Uint8Array;
+/**
+ * Hamming distance between two packed-bit vectors, normalized to [0, 1].
+ * @param dimensions Total number of bits for normalization. If omitted, uses byteLength * 8.
+ */
+export declare function hammingDistance(a: Uint8Array, b: Uint8Array, dimensions?: number): number;
+/**
+ * Hamming similarity: 1 - hammingDistance. Returns value in [0, 1].
+ */
+export declare function hammingSimilarity(a: Uint8Array, b: Uint8Array, dimensions?: number): number;
+/**
+ * Circular bit shift (permutation) for sequence encoding.
+ * Shifts the entire bit vector left by `shifts` positions, wrapping around.
+ */
+export declare function permute(v: Uint8Array, shifts?: number): Uint8Array;
+/**
+ * Token-based HDC pattern fingerprinter.
+ *
+ * Maps string tokens deterministically to hypervectors, then composes
+ * them via XOR binding. Suitable for Agent Booster Tier 1 fingerprinting
+ * where tokens like "slow", "flaky", "database" are composed into a
+ * single concept fingerprint.
+ */
+export declare class HDCPatternFingerprinter {
+    private readonly dimensions;
+    private readonly baseSeed;
+    private readonly byteLen;
+    private readonly tokenCache;
+    constructor(config?: {
+        dimensions?: number;
+        seed?: number;
+    });
+    /**
+     * Deterministic mapping from a string token to a hypervector.
+     * Uses seeded hash to generate bits. Results are cached.
+     */
+    tokenToHypervector(token: string): Uint8Array;
+    /**
+     * Bind all tokens: token1 XOR token2 XOR ... tokenN.
+     * XOR is commutative and associative, so order does not matter.
+     * Returns a zero vector for an empty token list.
+     */
+    fingerprintPattern(tokens: string[]): Uint8Array;
+    /**
+     * Bind tokens, then bundle with a context fingerprint.
+     * Context tokens are fingerprinted separately (via XOR bind) and
+     * then bundled (majority-rule) with the main token fingerprint.
+     */
+    fingerprintWithContext(tokens: string[], context: string[]): Uint8Array;
+    /** Hamming similarity between two vectors, normalized to [0, 1]. */
+    similarity(a: Uint8Array, b: Uint8Array): number;
+    private generateSeededVector;
+}
 /**
  * Hyperdimensional Computing fingerprinter for QE patterns.
  *
@@ -124,4 +192,12 @@ export declare class HdcFingerprinter {
  * ```
  */
 export declare function createHdcFingerprinter(config?: Partial<HdcConfig>): HdcFingerprinter;
+/**
+ * Feature-flag-gated factory for HDCPatternFingerprinter.
+ * Returns null when isHDCFingerprintingEnabled() is false.
+ */
+export declare function createHDCFingerprinter(config?: {
+    dimensions?: number;
+    seed?: number;
+}): HDCPatternFingerprinter | null;
 //# sourceMappingURL=hdc-fingerprint.d.ts.map