agentic-qe 3.8.11 → 3.8.13

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

@@ -0,0 +1,127 @@
+/**
+ * R1: Hyperdimensional Computing Pattern Fingerprinting
+ *
+ * 10,000-bit binary hypervectors with XOR binding for O(1) compositional
+ * pattern fingerprinting. TypeScript fallback implementation.
+ *
+ * When WASM is available (@ruvector/hdc-wasm), delegates to native SIMD-optimized ops.
+ * Without WASM, uses TypeScript Uint8Array bit operations.
+ *
+ * Key properties:
+ * - Deterministic: same input always produces the same fingerprint
+ * - Compositional: XOR binding combines multiple concepts into a single vector
+ * - Associative: bind(A, bind(B, C)) === bind(bind(A, B), C)
+ * - Distance-preserving: Hamming distance ≈ dimensions/2 for unrelated patterns
+ *
+ * @module integrations/ruvector/hdc-fingerprint
+ */
+/**
+ * Configuration for the HDC fingerprinter
+ */
+export interface HdcConfig {
+    /** Number of bits in each hypervector. Default: 10000 */
+    dimensions: number;
+    /** Seed for deterministic fingerprint generation */
+    seed?: number;
+}
+/**
+ * A pattern fingerprint represented as a packed binary hypervector
+ */
+export interface PatternFingerprint {
+    /** Packed bits: dimensions/8 bytes (1250 bytes for 10K dimensions) */
+    vector: Uint8Array;
+    /** Number of bits (dimensions) in the hypervector */
+    dimensions: number;
+    /** Hex hash for quick equality check */
+    hash: string;
+}
+/**
+ * Input data for fingerprinting a pattern
+ */
+export interface PatternInput {
+    id: string;
+    domain: string;
+    type: string;
+    content?: string;
+}
+/**
+ * Hyperdimensional Computing fingerprinter for QE patterns.
+ *
+ * Generates deterministic binary hypervectors from pattern metadata,
+ * supports XOR-based compositional binding, and provides Hamming
+ * distance / similarity metrics.
+ *
+ * @example
+ * ```typescript
+ * const hdc = new HdcFingerprinter();
+ * const fp = hdc.fingerprint({ id: 'p1', domain: 'security', type: 'xss' });
+ * console.log(fp.dimensions); // 10000
+ * console.log(fp.vector.length); // 1250
+ * ```
+ */
+export declare class HdcFingerprinter {
+    private readonly dimensions;
+    private readonly baseSeed;
+    constructor(config?: Partial<HdcConfig>);
+    /**
+     * Generate a deterministic fingerprint from pattern data.
+     *
+     * The fingerprint is seeded from a composite key of id + domain + type
+     * (and optionally content), ensuring identical inputs always produce
+     * identical outputs.
+     */
+    fingerprint(pattern: PatternInput): PatternFingerprint;
+    /**
+     * XOR-based compositional binding.
+     *
+     * Combines two hypervectors into a single vector representing their
+     * conjunction. XOR binding is:
+     * - Associative: bind(A, bind(B, C)) === bind(bind(A, B), C)
+     * - Commutative: bind(A, B) === bind(B, A)
+     * - Self-inverse: bind(A, A) === zero vector
+     *
+     * @param a First packed-bit vector
+     * @param b Second packed-bit vector
+     * @returns XOR of a and b (same length)
+     * @throws If vectors have different lengths
+     */
+    compositionalBind(a: Uint8Array, b: Uint8Array): Uint8Array;
+    /**
+     * Hamming distance between two packed-bit vectors.
+     *
+     * Counts the number of differing bits. For unrelated (random) vectors
+     * the expected distance is approximately dimensions / 2.
+     *
+     * @returns Number of differing bits (0 = identical, ~dimensions/2 = random)
+     * @throws If vectors have different lengths
+     */
+    hammingDistance(a: Uint8Array, b: Uint8Array): number;
+    /**
+     * Normalized similarity between two packed-bit vectors.
+     *
+     * @returns Value in [0, 1] where 1.0 = identical, 0.5 = random, 0.0 = opposite
+     */
+    similarity(a: Uint8Array, b: Uint8Array): number;
+    /**
+     * Batch fingerprint multiple patterns.
+     * Results match calling fingerprint() individually on each pattern.
+     */
+    batchFingerprint(patterns: PatternInput[]): PatternFingerprint[];
+    /**
+     * Generate a packed-bit vector from a seed using xorshift128 PRNG.
+     * Each bit is set with 50% probability, producing approximately
+     * dimensions/2 set bits on average.
+     */
+    private generateVector;
+}
+/**
+ * Create an HdcFingerprinter with the given configuration.
+ *
+ * @example
+ * ```typescript
+ * const hdc = createHdcFingerprinter({ dimensions: 10000 });
+ * const fp = hdc.fingerprint({ id: 'p1', domain: 'api', type: 'flaky' });
+ * ```
+ */
+export declare function createHdcFingerprinter(config?: Partial<HdcConfig>): HdcFingerprinter;
+//# sourceMappingURL=hdc-fingerprint.d.ts.map

package/dist/integrations/ruvector/hdc-fingerprint.js

@@ -0,0 +1,222 @@
+/**
+ * R1: Hyperdimensional Computing Pattern Fingerprinting
+ *
+ * 10,000-bit binary hypervectors with XOR binding for O(1) compositional
+ * pattern fingerprinting. TypeScript fallback implementation.
+ *
+ * When WASM is available (@ruvector/hdc-wasm), delegates to native SIMD-optimized ops.
+ * Without WASM, uses TypeScript Uint8Array bit operations.
+ *
+ * Key properties:
+ * - Deterministic: same input always produces the same fingerprint
+ * - Compositional: XOR binding combines multiple concepts into a single vector
+ * - Associative: bind(A, bind(B, C)) === bind(bind(A, B), C)
+ * - Distance-preserving: Hamming distance ≈ dimensions/2 for unrelated patterns
+ *
+ * @module integrations/ruvector/hdc-fingerprint
+ */
+import { Xorshift128 } from '../../shared/utils/xorshift128.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_DIMENSIONS = 10000;
+const DEFAULT_SEED = 0x811c9dc5; // FNV-1a offset basis
+// ============================================================================
+// Internal: FNV-1a Hash
+// ============================================================================
+/**
+ * FNV-1a 32-bit hash for deterministic seeding.
+ * Produces well-distributed values from arbitrary string input.
+ */
+function fnv1a(input) {
+    let hash = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193); // FNV prime
+    }
+    return hash >>> 0; // Ensure unsigned 32-bit
+}
+// ============================================================================
+// Internal: Popcount
+// ============================================================================
+/** Lookup table for popcount of a single byte (0-255) */
+const POPCOUNT_TABLE = new Uint8Array(256);
+for (let i = 0; i < 256; i++) {
+    let count = 0;
+    let n = i;
+    while (n) {
+        count++;
+        n &= n - 1; // Brian Kernighan's bit trick
+    }
+    POPCOUNT_TABLE[i] = count;
+}
+// ============================================================================
+// Internal: Hex encoding
+// ============================================================================
+const HEX_CHARS = '0123456789abcdef';
+/**
+ * Produce a hex string from the first 16 bytes of a Uint8Array
+ * (32-char hex digest, sufficient for quick equality checks).
+ */
+function hexDigest(bytes) {
+    const len = Math.min(bytes.length, 16);
+    let hex = '';
+    for (let i = 0; i < len; i++) {
+        const b = bytes[i];
+        hex += HEX_CHARS[b >> 4] + HEX_CHARS[b & 0x0f];
+    }
+    return hex;
+}
+// ============================================================================
+// HdcFingerprinter
+// ============================================================================
+/**
+ * Hyperdimensional Computing fingerprinter for QE patterns.
+ *
+ * Generates deterministic binary hypervectors from pattern metadata,
+ * supports XOR-based compositional binding, and provides Hamming
+ * distance / similarity metrics.
+ *
+ * @example
+ * ```typescript
+ * const hdc = new HdcFingerprinter();
+ * const fp = hdc.fingerprint({ id: 'p1', domain: 'security', type: 'xss' });
+ * console.log(fp.dimensions); // 10000
+ * console.log(fp.vector.length); // 1250
+ * ```
+ */
+export class HdcFingerprinter {
+    dimensions;
+    baseSeed;
+    constructor(config) {
+        this.dimensions = config?.dimensions ?? DEFAULT_DIMENSIONS;
+        this.baseSeed = config?.seed ?? DEFAULT_SEED;
+        if (this.dimensions <= 0) {
+            throw new Error(`HDC dimensions must be positive, got ${this.dimensions}`);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /**
+     * Generate a deterministic fingerprint from pattern data.
+     *
+     * The fingerprint is seeded from a composite key of id + domain + type
+     * (and optionally content), ensuring identical inputs always produce
+     * identical outputs.
+     */
+    fingerprint(pattern) {
+        const seedStr = `${pattern.id}|${pattern.domain}|${pattern.type}|${pattern.content ?? ''}`;
+        const seed = fnv1a(seedStr) ^ this.baseSeed;
+        const vector = this.generateVector(seed);
+        return {
+            vector,
+            dimensions: this.dimensions,
+            hash: hexDigest(vector),
+        };
+    }
+    /**
+     * XOR-based compositional binding.
+     *
+     * Combines two hypervectors into a single vector representing their
+     * conjunction. XOR binding is:
+     * - Associative: bind(A, bind(B, C)) === bind(bind(A, B), C)
+     * - Commutative: bind(A, B) === bind(B, A)
+     * - Self-inverse: bind(A, A) === zero vector
+     *
+     * @param a First packed-bit vector
+     * @param b Second packed-bit vector
+     * @returns XOR of a and b (same length)
+     * @throws If vectors have different lengths
+     */
+    compositionalBind(a, b) {
+        if (a.length !== b.length) {
+            throw new Error(`Cannot bind vectors of different lengths: ${a.length} vs ${b.length}`);
+        }
+        const result = new Uint8Array(a.length);
+        for (let i = 0; i < a.length; i++) {
+            result[i] = a[i] ^ b[i];
+        }
+        return result;
+    }
+    /**
+     * Hamming distance between two packed-bit vectors.
+     *
+     * Counts the number of differing bits. For unrelated (random) vectors
+     * the expected distance is approximately dimensions / 2.
+     *
+     * @returns Number of differing bits (0 = identical, ~dimensions/2 = random)
+     * @throws If vectors have different lengths
+     */
+    hammingDistance(a, b) {
+        if (a.length !== b.length) {
+            throw new Error(`Cannot compute Hamming distance for vectors of different lengths: ${a.length} vs ${b.length}`);
+        }
+        let distance = 0;
+        for (let i = 0; i < a.length; i++) {
+            distance += POPCOUNT_TABLE[a[i] ^ b[i]];
+        }
+        return distance;
+    }
+    /**
+     * Normalized similarity between two packed-bit vectors.
+     *
+     * @returns Value in [0, 1] where 1.0 = identical, 0.5 = random, 0.0 = opposite
+     */
+    similarity(a, b) {
+        const dist = this.hammingDistance(a, b);
+        return 1 - dist / this.dimensions;
+    }
+    /**
+     * Batch fingerprint multiple patterns.
+     * Results match calling fingerprint() individually on each pattern.
+     */
+    batchFingerprint(patterns) {
+        return patterns.map((p) => this.fingerprint(p));
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    /**
+     * Generate a packed-bit vector from a seed using xorshift128 PRNG.
+     * Each bit is set with 50% probability, producing approximately
+     * dimensions/2 set bits on average.
+     */
+    generateVector(seed) {
+        const byteLen = Math.ceil(this.dimensions / 8);
+        const vector = new Uint8Array(byteLen);
+        const rng = new Xorshift128(seed);
+        // Fill 4 bytes at a time from each 32-bit random value
+        let byteIdx = 0;
+        while (byteIdx < byteLen) {
+            const rand = rng.next();
+            const remaining = byteLen - byteIdx;
+            const count = remaining < 4 ? remaining : 4;
+            for (let j = 0; j < count; j++) {
+                vector[byteIdx++] = (rand >>> (j * 8)) & 0xff;
+            }
+        }
+        // Mask unused trailing bits in the last byte
+        const trailingBits = this.dimensions % 8;
+        if (trailingBits > 0) {
+            vector[byteLen - 1] &= (1 << trailingBits) - 1;
+        }
+        return vector;
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create an HdcFingerprinter with the given configuration.
+ *
+ * @example
+ * ```typescript
+ * const hdc = createHdcFingerprinter({ dimensions: 10000 });
+ * const fp = hdc.fingerprint({ id: 'p1', domain: 'api', type: 'flaky' });
+ * ```
+ */
+export function createHdcFingerprinter(config) {
+    return new HdcFingerprinter(config);
+}
+//# sourceMappingURL=hdc-fingerprint.js.map

package/dist/integrations/ruvector/hopfield-memory.d.ts

@@ -0,0 +1,97 @@
+/**
+ * R5: Modern Hopfield Networks — Associative Pattern Memory
+ *
+ * Exponential-capacity content-addressable memory for exact pattern recall.
+ * Complements HNSW approximate nearest neighbor with exact retrieval:
+ * - HNSW: "What patterns are similar?" (approximate)
+ * - Hopfield: "Did we see exactly this pattern before?" (exact)
+ *
+ * Based on Ramsauer et al. 2020 "Hopfield Networks is All You Need".
+ * TypeScript implementation; WASM upgrade path via @ruvector/hopfield-wasm.
+ *
+ * @module integrations/ruvector/hopfield-memory
+ */
+/**
+ * Configuration for the Hopfield associative memory
+ */
+export interface HopfieldConfig {
+    /** Pattern dimension. Default: 128 */
+    dimension: number;
+    /** Inverse temperature beta controlling sharpness of retrieval. Higher = more exact. Default: 8.0 */
+    beta: number;
+    /** Maximum number of stored patterns. Default: 10000 */
+    maxPatterns: number;
+}
+/**
+ * A pattern stored in Hopfield memory with associated metadata
+ */
+export interface StoredPattern {
+    /** The pattern vector */
+    pattern: Float32Array;
+    /** Associated metadata */
+    metadata: Record<string, unknown>;
+    /** Timestamp of storage */
+    storedAt: number;
+}
+/**
+ * Result of a Hopfield recall operation
+ */
+export interface RecallResult {
+    /** Retrieved pattern (closest stored pattern) */
+    pattern: Float32Array;
+    /** Metadata associated with the retrieved pattern */
+    metadata: Record<string, unknown>;
+    /** Hopfield energy of the retrieval (lower = more confident) */
+    energy: number;
+    /** Cosine similarity between query and retrieved pattern */
+    similarity: number;
+}
+/**
+ * Modern Hopfield Network for associative pattern memory.
+ *
+ * Update rule: new_state = X * softmax(beta * X^T * query).
+ * High beta (default 8.0) makes softmax approach argmax for exact recall.
+ */
+export declare class HopfieldMemory {
+    private readonly dimension;
+    private readonly beta;
+    private readonly maxPatterns;
+    private readonly patterns;
+    constructor(config?: Partial<HopfieldConfig>);
+    /** Store a pattern. L2-normalizes, validates dimension; evicts oldest if at capacity. */
+    store(pattern: Float32Array, metadata?: Record<string, unknown>): void;
+    /**
+     * Recall the closest stored pattern via softmax(beta * X^T * query).
+     * Returns null if empty.
+     *
+     * Note: With normalized patterns and beta=8, softmax strongly concentrates
+     * on the nearest pattern (argmax), making this equivalent to a single
+     * Hopfield fixed-point iteration that converges immediately (Ramsauer 2020,
+     * Theorem 3). Full iterative convergence is unnecessary at high beta.
+     */
+    recall(query: Float32Array): RecallResult | null;
+    /** Recall multiple queries in batch. */
+    batchRecall(queries: Float32Array[]): (RecallResult | null)[];
+    /** Get the number of stored patterns. */
+    getPatternCount(): number;
+    /** Remove all stored patterns. */
+    clear(): void;
+    /**
+     * Hopfield energy: E = -lse(beta, X^T * state) + 0.5 * ||state||^2.
+     * Lower energy = closer to a stored pattern. State is L2-normalized first.
+     */
+    getEnergy(state: Float32Array): number;
+    /** Numerically stable softmax: subtract max before exp to avoid overflow. */
+    private softmax;
+    /** Dot product of two Float32Arrays. */
+    private dotProduct;
+    /** Cosine similarity in [-1, 1]. */
+    private cosineSimilarity;
+    /** L2 normalization. Returns unit-length copy (or zero vector if input is zero). */
+    private normalize;
+    /** Assert that the useHopfieldMemory feature flag is enabled. */
+    private assertEnabled;
+}
+/** Create a HopfieldMemory with the given configuration. */
+export declare function createHopfieldMemory(config?: Partial<HopfieldConfig>): HopfieldMemory;
+//# sourceMappingURL=hopfield-memory.d.ts.map

package/dist/integrations/ruvector/hopfield-memory.js

@@ -0,0 +1,238 @@
+/**
+ * R5: Modern Hopfield Networks — Associative Pattern Memory
+ *
+ * Exponential-capacity content-addressable memory for exact pattern recall.
+ * Complements HNSW approximate nearest neighbor with exact retrieval:
+ * - HNSW: "What patterns are similar?" (approximate)
+ * - Hopfield: "Did we see exactly this pattern before?" (exact)
+ *
+ * Based on Ramsauer et al. 2020 "Hopfield Networks is All You Need".
+ * TypeScript implementation; WASM upgrade path via @ruvector/hopfield-wasm.
+ *
+ * @module integrations/ruvector/hopfield-memory
+ */
+import { getRuVectorFeatureFlags } from './feature-flags.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_DIMENSION = 128;
+const DEFAULT_BETA = 8.0;
+const DEFAULT_MAX_PATTERNS = 10000;
+// ============================================================================
+// HopfieldMemory
+// ============================================================================
+/**
+ * Modern Hopfield Network for associative pattern memory.
+ *
+ * Update rule: new_state = X * softmax(beta * X^T * query).
+ * High beta (default 8.0) makes softmax approach argmax for exact recall.
+ */
+export class HopfieldMemory {
+    dimension;
+    beta;
+    maxPatterns;
+    patterns;
+    constructor(config) {
+        this.dimension = config?.dimension ?? DEFAULT_DIMENSION;
+        this.beta = config?.beta ?? DEFAULT_BETA;
+        this.maxPatterns = config?.maxPatterns ?? DEFAULT_MAX_PATTERNS;
+        this.patterns = [];
+        if (this.dimension <= 0) {
+            throw new Error(`Hopfield dimension must be positive, got ${this.dimension}`);
+        }
+        if (this.beta <= 0) {
+            throw new Error(`Hopfield beta must be positive, got ${this.beta}`);
+        }
+        if (this.maxPatterns <= 0) {
+            throw new Error(`Hopfield maxPatterns must be positive, got ${this.maxPatterns}`);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Public API
+    // --------------------------------------------------------------------------
+    /** Store a pattern. L2-normalizes, validates dimension; evicts oldest if at capacity. */
+    store(pattern, metadata) {
+        this.assertEnabled();
+        if (pattern.length !== this.dimension) {
+            throw new Error(`Pattern dimension mismatch: expected ${this.dimension}, got ${pattern.length}`);
+        }
+        // Reject zero-magnitude vectors (would be unretrievable after normalization)
+        const mag = this.dotProduct(pattern, pattern);
+        if (mag === 0) {
+            throw new Error('Cannot store zero-magnitude pattern in Hopfield memory');
+        }
+        // L2-normalize for consistent softmax attention weights
+        const normalized = this.normalize(pattern);
+        // Evict oldest if at capacity
+        if (this.patterns.length >= this.maxPatterns) {
+            this.patterns.shift();
+        }
+        this.patterns.push({
+            pattern: normalized,
+            metadata: metadata ?? {},
+            storedAt: Date.now(),
+        });
+    }
+    /**
+     * Recall the closest stored pattern via softmax(beta * X^T * query).
+     * Returns null if empty.
+     *
+     * Note: With normalized patterns and beta=8, softmax strongly concentrates
+     * on the nearest pattern (argmax), making this equivalent to a single
+     * Hopfield fixed-point iteration that converges immediately (Ramsauer 2020,
+     * Theorem 3). Full iterative convergence is unnecessary at high beta.
+     */
+    recall(query) {
+        this.assertEnabled();
+        if (query.length !== this.dimension) {
+            throw new Error(`Query dimension mismatch: expected ${this.dimension}, got ${query.length}`);
+        }
+        if (this.patterns.length === 0) {
+            return null;
+        }
+        // L2-normalize query for magnitude-invariant comparison
+        const normalizedQuery = this.normalize(query);
+        // Compute logits: beta * X^T * normalizedQuery
+        const logits = new Float32Array(this.patterns.length);
+        for (let i = 0; i < this.patterns.length; i++) {
+            logits[i] = this.beta * this.dotProduct(this.patterns[i].pattern, normalizedQuery);
+        }
+        // Softmax to get attention weights
+        const weights = this.softmax(logits);
+        // Find the pattern with the highest attention weight
+        let bestIdx = 0;
+        let bestWeight = weights[0];
+        for (let i = 1; i < weights.length; i++) {
+            if (weights[i] > bestWeight) {
+                bestWeight = weights[i];
+                bestIdx = i;
+            }
+        }
+        const matched = this.patterns[bestIdx];
+        const energy = this.getEnergy(normalizedQuery);
+        const similarity = this.cosineSimilarity(normalizedQuery, matched.pattern);
+        return {
+            pattern: new Float32Array(matched.pattern),
+            metadata: { ...matched.metadata },
+            energy,
+            similarity,
+        };
+    }
+    /** Recall multiple queries in batch. */
+    batchRecall(queries) {
+        this.assertEnabled();
+        return queries.map((q) => this.recall(q));
+    }
+    /** Get the number of stored patterns. */
+    getPatternCount() {
+        return this.patterns.length;
+    }
+    /** Remove all stored patterns. */
+    clear() {
+        this.patterns.length = 0;
+    }
+    /**
+     * Hopfield energy: E = -lse(beta, X^T * state) + 0.5 * ||state||^2.
+     * Lower energy = closer to a stored pattern. State is L2-normalized first.
+     */
+    getEnergy(state) {
+        if (state.length !== this.dimension) {
+            throw new Error(`State dimension mismatch: expected ${this.dimension}, got ${state.length}`);
+        }
+        // L2-normalize state for consistent energy computation
+        const normalizedState = this.normalize(state);
+        if (this.patterns.length === 0) {
+            // Only the quadratic term remains; normalized state has ||s||^2 = 1
+            return 0.5 * this.dotProduct(normalizedState, normalizedState);
+        }
+        // Compute z_i = X^T * normalizedState (dot products with each stored pattern)
+        const z = new Float32Array(this.patterns.length);
+        for (let i = 0; i < this.patterns.length; i++) {
+            z[i] = this.dotProduct(this.patterns[i].pattern, normalizedState);
+        }
+        // Numerically stable lse: (1/beta) * (max + log(sum(exp(beta*z_i - max))))
+        const scaledZ = new Float32Array(this.patterns.length);
+        let maxVal = -Infinity;
+        for (let i = 0; i < this.patterns.length; i++) {
+            scaledZ[i] = this.beta * z[i];
+            if (scaledZ[i] > maxVal)
+                maxVal = scaledZ[i];
+        }
+        let sumExp = 0;
+        for (let i = 0; i < this.patterns.length; i++) {
+            sumExp += Math.exp(scaledZ[i] - maxVal);
+        }
+        const lse = (1 / this.beta) * (maxVal + Math.log(sumExp));
+        // E = -lse + 0.5 * ||normalizedState||^2
+        const normSq = this.dotProduct(normalizedState, normalizedState);
+        return -lse + 0.5 * normSq;
+    }
+    // --------------------------------------------------------------------------
+    // Internal Helpers
+    // --------------------------------------------------------------------------
+    /** Numerically stable softmax: subtract max before exp to avoid overflow. */
+    softmax(logits) {
+        const result = new Float32Array(logits.length);
+        // Find max for numerical stability
+        let maxVal = -Infinity;
+        for (let i = 0; i < logits.length; i++) {
+            if (logits[i] > maxVal)
+                maxVal = logits[i];
+        }
+        // Compute exp(x - max) and sum
+        let sum = 0;
+        for (let i = 0; i < logits.length; i++) {
+            result[i] = Math.exp(logits[i] - maxVal);
+            sum += result[i];
+        }
+        // Normalize
+        if (sum > 0) {
+            for (let i = 0; i < result.length; i++) {
+                result[i] /= sum;
+            }
+        }
+        return result;
+    }
+    /** Dot product of two Float32Arrays. */
+    dotProduct(a, b) {
+        let sum = 0;
+        for (let i = 0; i < a.length; i++) {
+            sum += a[i] * b[i];
+        }
+        return sum;
+    }
+    /** Cosine similarity in [-1, 1]. */
+    cosineSimilarity(a, b) {
+        const dot = this.dotProduct(a, b);
+        const normA = Math.sqrt(this.dotProduct(a, a));
+        const normB = Math.sqrt(this.dotProduct(b, b));
+        if (normA === 0 || normB === 0)
+            return 0;
+        return dot / (normA * normB);
+    }
+    /** L2 normalization. Returns unit-length copy (or zero vector if input is zero). */
+    normalize(v) {
+        const norm = Math.sqrt(this.dotProduct(v, v));
+        const result = new Float32Array(v.length);
+        if (norm > 0) {
+            for (let i = 0; i < v.length; i++) {
+                result[i] = v[i] / norm;
+            }
+        }
+        return result;
+    }
+    /** Assert that the useHopfieldMemory feature flag is enabled. */
+    assertEnabled() {
+        if (!getRuVectorFeatureFlags().useHopfieldMemory) {
+            throw new Error('Hopfield memory is disabled (useHopfieldMemory feature flag is false)');
+        }
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/** Create a HopfieldMemory with the given configuration. */
+export function createHopfieldMemory(config) {
+    return new HopfieldMemory(config);
+}
+//# sourceMappingURL=hopfield-memory.js.map