agentic-qe 3.7.22 → 3.8.1

package/dist/integrations/browser/qe-dashboard/wasm-vector-store.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Browser-side WASM Vector Store for QE Dashboard (Task 4.6)
+ *
+ * Provides a vector store that attempts to load `rvlite` for WASM-based
+ * vector search. When unavailable, falls back to a lightweight in-memory
+ * vector store with cosine similarity search and namespace support.
+ *
+ * Design Goals:
+ * - No browser-specific APIs (must work in Node.js for testing)
+ * - All WASM imports are optional with TypeScript fallback
+ * - Efficient cosine similarity computation
+ * - Namespace-scoped vector storage
+ *
+ * @module integrations/browser/qe-dashboard/wasm-vector-store
+ */
+/** Result of a similarity search */
+export interface SearchResult {
+    /** Unique identifier for the matched vector */
+    id: string;
+    /** Cosine similarity score (0..1 for normalized vectors, -1..1 otherwise) */
+    similarity: number;
+    /** Metadata associated with the vector */
+    metadata: Record<string, unknown>;
+    /** Namespace the vector belongs to */
+    namespace?: string;
+}
+/** Statistics about the vector store */
+export interface StoreStats {
+    /** Total number of vectors stored */
+    totalVectors: number;
+    /** Number of distinct namespaces */
+    namespaceCount: number;
+    /** Vectors per namespace */
+    namespaceSizes: Record<string, number>;
+    /** Dimensionality of stored vectors (0 if empty) */
+    dimensions: number;
+    /** Whether the WASM backend is active */
+    wasmActive: boolean;
+    /** Approximate memory usage in bytes */
+    memoryBytes: number;
+}
+/**
+ * Compute cosine similarity between two vectors
+ *
+ * cosine_similarity = dot(a, b) / (||a|| * ||b||)
+ *
+ * Optimized to accept pre-computed norms for repeated queries.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array, normA?: number, normB?: number): number;
+/**
+ * Browser-side vector store with optional WASM acceleration.
+ *
+ * Tries to load `rvlite` for WASM-based vector search. When unavailable,
+ * uses a pure TypeScript in-memory implementation with cosine similarity.
+ *
+ * @example
+ * ```typescript
+ * const store = new WasmVectorStore();
+ * await store.initialize();
+ *
+ * // Add vectors
+ * store.add('pattern-1', new Float32Array([0.1, 0.2, 0.3]), { domain: 'testing' });
+ * store.add('pattern-2', new Float32Array([0.4, 0.5, 0.6]), { domain: 'coverage' });
+ *
+ * // Search
+ * const results = store.search(new Float32Array([0.1, 0.2, 0.3]), 5);
+ * console.log(results[0].id); // 'pattern-1'
+ * console.log(results[0].similarity); // ~1.0
+ * ```
+ */
+export declare class WasmVectorStore {
+    private vectors;
+    private wasmModule;
+    private dimensions;
+    private initialized;
+    /**
+     * Initialize the vector store
+     *
+     * Attempts to load the WASM backend. Falls back to TypeScript if unavailable.
+     * Safe to call multiple times (idempotent).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Add a vector with optional metadata and namespace
+     *
+     * @param id - Unique identifier for the vector
+     * @param vector - The vector data as Float32Array
+     * @param metadata - Optional key-value metadata
+     * @param namespace - Optional namespace for scoped queries (default: 'default')
+     * @throws Error if vector dimensions are inconsistent
+     */
+    add(id: string, vector: Float32Array, metadata?: Record<string, unknown>, namespace?: string): void;
+    /**
+     * Search for the k most similar vectors to a query
+     *
+     * @param query - The query vector
+     * @param k - Number of results to return
+     * @param namespace - Optional namespace filter (searches all if omitted)
+     * @returns Array of SearchResult sorted by descending similarity
+     */
+    search(query: Float32Array, k: number, namespace?: string): SearchResult[];
+    /**
+     * Remove a vector by id
+     *
+     * @param id - The vector id to remove
+     * @returns true if the vector was found and removed, false otherwise
+     */
+    remove(id: string): boolean;
+    /**
+     * Check if a vector exists
+     *
+     * @param id - The vector id to check
+     * @returns true if a vector with this id exists
+     */
+    has(id: string): boolean;
+    /**
+     * Get the number of stored vectors
+     */
+    get size(): number;
+    /**
+     * Clear all vectors, optionally within a specific namespace
+     *
+     * @param namespace - If provided, only clear vectors in this namespace
+     */
+    clear(namespace?: string): void;
+    /**
+     * Get store statistics
+     *
+     * @returns StoreStats with counts, dimensions, memory usage, etc.
+     */
+    getStats(): StoreStats;
+    /**
+     * Get all vector ids, optionally filtered by namespace
+     *
+     * @param namespace - Optional namespace filter
+     * @returns Array of vector ids
+     */
+    getIds(namespace?: string): string[];
+    /**
+     * Whether the WASM backend is loaded
+     */
+    get isWasmActive(): boolean;
+}
+//# sourceMappingURL=wasm-vector-store.d.ts.map

package/dist/integrations/browser/qe-dashboard/wasm-vector-store.js

@@ -0,0 +1,277 @@
+/**
+ * Browser-side WASM Vector Store for QE Dashboard (Task 4.6)
+ *
+ * Provides a vector store that attempts to load `rvlite` for WASM-based
+ * vector search. When unavailable, falls back to a lightweight in-memory
+ * vector store with cosine similarity search and namespace support.
+ *
+ * Design Goals:
+ * - No browser-specific APIs (must work in Node.js for testing)
+ * - All WASM imports are optional with TypeScript fallback
+ * - Efficient cosine similarity computation
+ * - Namespace-scoped vector storage
+ *
+ * @module integrations/browser/qe-dashboard/wasm-vector-store
+ */
+// ============================================================================
+// Math Utilities
+// ============================================================================
+/**
+ * Compute the L2 norm of a vector
+ */
+function l2Norm(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        sum += v[i] * v[i];
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Compute cosine similarity between two vectors
+ *
+ * cosine_similarity = dot(a, b) / (||a|| * ||b||)
+ *
+ * Optimized to accept pre-computed norms for repeated queries.
+ */
+export function cosineSimilarity(a, b, normA, normB) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+    }
+    const na = normA ?? l2Norm(a);
+    const nb = normB ?? l2Norm(b);
+    if (na === 0 || nb === 0) {
+        return 0;
+    }
+    return dot / (na * nb);
+}
+/**
+ * Attempt to load the rvlite WASM module
+ * Returns null if unavailable (expected in most environments)
+ */
+async function tryLoadRvlite() {
+    try {
+        // Dynamic import - will fail gracefully if rvlite is not installed
+        const rvlite = await import('rvlite');
+        if (rvlite && typeof rvlite.add === 'function') {
+            return rvlite;
+        }
+        return null;
+    }
+    catch {
+        // Expected: rvlite is not installed in most environments
+        return null;
+    }
+}
+// ============================================================================
+// WasmVectorStore
+// ============================================================================
+/**
+ * Browser-side vector store with optional WASM acceleration.
+ *
+ * Tries to load `rvlite` for WASM-based vector search. When unavailable,
+ * uses a pure TypeScript in-memory implementation with cosine similarity.
+ *
+ * @example
+ * ```typescript
+ * const store = new WasmVectorStore();
+ * await store.initialize();
+ *
+ * // Add vectors
+ * store.add('pattern-1', new Float32Array([0.1, 0.2, 0.3]), { domain: 'testing' });
+ * store.add('pattern-2', new Float32Array([0.4, 0.5, 0.6]), { domain: 'coverage' });
+ *
+ * // Search
+ * const results = store.search(new Float32Array([0.1, 0.2, 0.3]), 5);
+ * console.log(results[0].id); // 'pattern-1'
+ * console.log(results[0].similarity); // ~1.0
+ * ```
+ */
+export class WasmVectorStore {
+    vectors = new Map();
+    wasmModule = null;
+    dimensions = 0;
+    initialized = false;
+    /**
+     * Initialize the vector store
+     *
+     * Attempts to load the WASM backend. Falls back to TypeScript if unavailable.
+     * Safe to call multiple times (idempotent).
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.wasmModule = await tryLoadRvlite();
+        this.initialized = true;
+    }
+    /**
+     * Add a vector with optional metadata and namespace
+     *
+     * @param id - Unique identifier for the vector
+     * @param vector - The vector data as Float32Array
+     * @param metadata - Optional key-value metadata
+     * @param namespace - Optional namespace for scoped queries (default: 'default')
+     * @throws Error if vector dimensions are inconsistent
+     */
+    add(id, vector, metadata = {}, namespace = 'default') {
+        if (vector.length === 0) {
+            throw new Error('Cannot add zero-length vector');
+        }
+        // Enforce consistent dimensionality
+        if (this.dimensions === 0) {
+            this.dimensions = vector.length;
+        }
+        else if (vector.length !== this.dimensions) {
+            throw new Error(`Dimension mismatch: expected ${this.dimensions}, got ${vector.length}`);
+        }
+        // Delegate to WASM if available
+        if (this.wasmModule) {
+            this.wasmModule.add(id, vector, namespace);
+            // Still keep in JS map for metadata lookups
+        }
+        const norm = l2Norm(vector);
+        this.vectors.set(id, { vector, metadata, namespace, norm });
+    }
+    /**
+     * Search for the k most similar vectors to a query
+     *
+     * @param query - The query vector
+     * @param k - Number of results to return
+     * @param namespace - Optional namespace filter (searches all if omitted)
+     * @returns Array of SearchResult sorted by descending similarity
+     */
+    search(query, k, namespace) {
+        if (query.length === 0) {
+            return [];
+        }
+        if (this.vectors.size === 0) {
+            return [];
+        }
+        // Dimension check for query
+        if (this.dimensions > 0 && query.length !== this.dimensions) {
+            throw new Error(`Query dimension mismatch: expected ${this.dimensions}, got ${query.length}`);
+        }
+        const queryNorm = l2Norm(query);
+        const results = [];
+        for (const [id, entry] of this.vectors) {
+            // Namespace filter
+            if (namespace !== undefined && entry.namespace !== namespace) {
+                continue;
+            }
+            const similarity = cosineSimilarity(query, entry.vector, queryNorm, entry.norm);
+            results.push({
+                id,
+                similarity,
+                metadata: { ...entry.metadata },
+                namespace: entry.namespace,
+            });
+        }
+        // Sort by descending similarity
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, Math.max(0, k));
+    }
+    /**
+     * Remove a vector by id
+     *
+     * @param id - The vector id to remove
+     * @returns true if the vector was found and removed, false otherwise
+     */
+    remove(id) {
+        if (this.wasmModule) {
+            this.wasmModule.remove(id);
+        }
+        const existed = this.vectors.delete(id);
+        // Reset dimensions if store is now empty
+        if (this.vectors.size === 0) {
+            this.dimensions = 0;
+        }
+        return existed;
+    }
+    /**
+     * Check if a vector exists
+     *
+     * @param id - The vector id to check
+     * @returns true if a vector with this id exists
+     */
+    has(id) {
+        return this.vectors.has(id);
+    }
+    /**
+     * Get the number of stored vectors
+     */
+    get size() {
+        return this.vectors.size;
+    }
+    /**
+     * Clear all vectors, optionally within a specific namespace
+     *
+     * @param namespace - If provided, only clear vectors in this namespace
+     */
+    clear(namespace) {
+        if (namespace === undefined) {
+            this.vectors.clear();
+            this.dimensions = 0;
+        }
+        else {
+            for (const [id, entry] of this.vectors) {
+                if (entry.namespace === namespace) {
+                    this.vectors.delete(id);
+                }
+            }
+            if (this.vectors.size === 0) {
+                this.dimensions = 0;
+            }
+        }
+    }
+    /**
+     * Get store statistics
+     *
+     * @returns StoreStats with counts, dimensions, memory usage, etc.
+     */
+    getStats() {
+        const namespaceSizes = {};
+        let memoryBytes = 0;
+        for (const [, entry] of this.vectors) {
+            const ns = entry.namespace;
+            namespaceSizes[ns] = (namespaceSizes[ns] || 0) + 1;
+            // Approximate: Float32Array bytes + metadata overhead
+            memoryBytes += entry.vector.byteLength + 128;
+        }
+        return {
+            totalVectors: this.vectors.size,
+            namespaceCount: Object.keys(namespaceSizes).length,
+            namespaceSizes,
+            dimensions: this.dimensions,
+            wasmActive: this.wasmModule !== null,
+            memoryBytes,
+        };
+    }
+    /**
+     * Get all vector ids, optionally filtered by namespace
+     *
+     * @param namespace - Optional namespace filter
+     * @returns Array of vector ids
+     */
+    getIds(namespace) {
+        if (namespace === undefined) {
+            return Array.from(this.vectors.keys());
+        }
+        const ids = [];
+        for (const [id, entry] of this.vectors) {
+            if (entry.namespace === namespace) {
+                ids.push(id);
+            }
+        }
+        return ids;
+    }
+    /**
+     * Whether the WASM backend is loaded
+     */
+    get isWasmActive() {
+        return this.wasmModule !== null;
+    }
+}
+//# sourceMappingURL=wasm-vector-store.js.map

package/dist/integrations/ruvector/cognitive-container-codec.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cognitive Container Binary Codec (Task 4.1)
+ *
+ * Binary pack/unpack helpers for the cognitive container format.
+ * Separated from cognitive-container.ts to keep each file under 500 lines.
+ *
+ * Binary layout:
+ *   [MAGIC 8B][VERSION 4B][MANIFEST_LEN 4B][MANIFEST JSON][SEGMENT DATA...]
+ *
+ * @module integrations/ruvector/cognitive-container-codec
+ */
+import { Buffer } from 'buffer';
+import Database from 'better-sqlite3';
+import type { ContainerManifest, ContainerSegment } from './cognitive-container.js';
+/** 8-byte magic header: "COGCNTNR" */
+export declare const MAGIC: Buffer<ArrayBuffer>;
+/** Current container format version */
+export declare const FORMAT_VERSION = 2;
+/** Segment names in canonical order */
+export declare const SEGMENT_NAMES: readonly ["patterns", "embeddings", "q-values", "lora-weights", "graph", "witness-chain"];
+export type SegmentName = (typeof SEGMENT_NAMES)[number];
+/** SHA-256 hash of a Buffer, returned as hex. */
+export declare function sha256buf(data: Buffer): string;
+/**
+ * Collect all table data from the database, grouped by segment.
+ */
+export declare function collectSegmentData(db: Database.Database, domains?: readonly string[]): Record<SegmentName, Record<string, unknown[]>>;
+/**
+ * Serialize a segment's data map to a Buffer, optionally compressed.
+ */
+export declare function serializeSegment(data: Record<string, unknown[]>, compress: boolean): Buffer;
+/**
+ * Deserialize a segment Buffer back to its data map.
+ */
+export declare function deserializeSegment(buf: Buffer, compressed: boolean): Record<string, unknown[]>;
+/**
+ * Write the container binary from a manifest and segment buffers.
+ */
+export declare function packContainer(manifest: ContainerManifest, segmentBuffers: Buffer[]): Buffer;
+/**
+ * Parse the header from container data and return manifest + data offset.
+ */
+export declare function unpackHeader(data: Buffer): {
+    manifest: ContainerManifest;
+    dataOffset: number;
+};
+/**
+ * Extract segment buffers from container data using manifest offsets.
+ */
+export declare function extractSegments(data: Buffer, dataOffset: number, segments: ContainerSegment[]): Map<string, Buffer>;
+//# sourceMappingURL=cognitive-container-codec.d.ts.map

package/dist/integrations/ruvector/cognitive-container-codec.js

@@ -0,0 +1,180 @@
+/**
+ * Cognitive Container Binary Codec (Task 4.1)
+ *
+ * Binary pack/unpack helpers for the cognitive container format.
+ * Separated from cognitive-container.ts to keep each file under 500 lines.
+ *
+ * Binary layout:
+ *   [MAGIC 8B][VERSION 4B][MANIFEST_LEN 4B][MANIFEST JSON][SEGMENT DATA...]
+ *
+ * @module integrations/ruvector/cognitive-container-codec
+ */
+import { createHash } from 'crypto';
+import { Buffer } from 'buffer';
+import { gunzipSync, gzipSync } from 'zlib';
+import { queryAll, domainFilterForColumn, serializeRowBlobs, TABLE_CONFIGS, TABLE_BLOB_COLUMNS, } from './brain-shared.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** 8-byte magic header: "COGCNTNR" */
+export const MAGIC = Buffer.from('COGCNTNR', 'ascii');
+/** Current container format version */
+export const FORMAT_VERSION = 2;
+/** Segment names in canonical order */
+export const SEGMENT_NAMES = [
+    'patterns',
+    'embeddings',
+    'q-values',
+    'lora-weights',
+    'graph',
+    'witness-chain',
+];
+// ============================================================================
+// Helpers
+// ============================================================================
+/** SHA-256 hash of a Buffer, returned as hex. */
+export function sha256buf(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** Table name to segment name mapping. */
+const TABLE_TO_SEGMENT = {
+    qe_patterns: 'patterns',
+    qe_pattern_embeddings: 'embeddings',
+    captured_experiences: 'embeddings',
+    sona_patterns: 'embeddings',
+    rl_q_values: 'q-values',
+    dream_cycles: 'lora-weights',
+    dream_insights: 'lora-weights',
+    concept_nodes: 'graph',
+    concept_edges: 'graph',
+    witness_chain: 'witness-chain',
+};
+/** Assign a segment name for a given table. Defaults to 'patterns'. */
+function segmentForTable(tableName) {
+    return TABLE_TO_SEGMENT[tableName] ?? 'patterns';
+}
+// ============================================================================
+// Data Collection
+// ============================================================================
+/**
+ * Collect all table data from the database, grouped by segment.
+ */
+export function collectSegmentData(db, domains) {
+    const segments = {
+        'patterns': {},
+        'embeddings': {},
+        'q-values': {},
+        'lora-weights': {},
+        'graph': {},
+        'witness-chain': {},
+    };
+    for (const config of TABLE_CONFIGS) {
+        const [where, params] = config.domainColumn
+            ? domainFilterForColumn(domains, config.domainColumn)
+            : [undefined, []];
+        let rows = queryAll(db, config.tableName, where, params);
+        const blobCols = TABLE_BLOB_COLUMNS[config.tableName];
+        if (blobCols && blobCols.length > 0) {
+            rows = rows.map(r => serializeRowBlobs(r, blobCols));
+        }
+        const seg = segmentForTable(config.tableName);
+        segments[seg][config.tableName] = rows;
+    }
+    return segments;
+}
+// ============================================================================
+// Segment Serialization
+// ============================================================================
+/**
+ * Serialize a segment's data map to a Buffer, optionally compressed.
+ */
+export function serializeSegment(data, compress) {
+    const json = JSON.stringify(data);
+    const raw = Buffer.from(json, 'utf-8');
+    if (compress) {
+        return gzipSync(raw);
+    }
+    return raw;
+}
+/**
+ * Deserialize a segment Buffer back to its data map.
+ */
+export function deserializeSegment(buf, compressed) {
+    const raw = compressed ? gunzipSync(buf) : buf;
+    return JSON.parse(raw.toString('utf-8'));
+}
+// ============================================================================
+// Binary Packing
+// ============================================================================
+/**
+ * Write the container binary from a manifest and segment buffers.
+ */
+export function packContainer(manifest, segmentBuffers) {
+    const manifestJson = JSON.stringify(manifest);
+    const manifestBuf = Buffer.from(manifestJson, 'utf-8');
+    const headerLen = MAGIC.length + 4 + 4; // MAGIC(8) + VERSION(4) + MANIFEST_LEN(4)
+    const totalDataLen = segmentBuffers.reduce((sum, b) => sum + b.length, 0);
+    const totalLen = headerLen + manifestBuf.length + totalDataLen;
+    const out = Buffer.alloc(totalLen);
+    let pos = 0;
+    MAGIC.copy(out, pos);
+    pos += MAGIC.length;
+    out.writeUInt32BE(FORMAT_VERSION, pos);
+    pos += 4;
+    out.writeUInt32BE(manifestBuf.length, pos);
+    pos += 4;
+    manifestBuf.copy(out, pos);
+    pos += manifestBuf.length;
+    for (const buf of segmentBuffers) {
+        buf.copy(out, pos);
+        pos += buf.length;
+    }
+    return out;
+}
+/**
+ * Parse the header from container data and return manifest + data offset.
+ */
+export function unpackHeader(data) {
+    if (data.length < 16) {
+        throw new Error('Container too small: missing header');
+    }
+    const magic = data.subarray(0, MAGIC.length);
+    if (!magic.equals(MAGIC)) {
+        throw new Error('Invalid container: bad magic bytes');
+    }
+    const version = data.readUInt32BE(MAGIC.length);
+    if (version !== FORMAT_VERSION) {
+        throw new Error(`Unsupported container version: ${version}`);
+    }
+    const manifestLen = data.readUInt32BE(MAGIC.length + 4);
+    const manifestStart = MAGIC.length + 8;
+    const manifestEnd = manifestStart + manifestLen;
+    if (data.length < manifestEnd) {
+        throw new Error('Container truncated: manifest extends beyond data');
+    }
+    const manifestJson = data.subarray(manifestStart, manifestEnd).toString('utf-8');
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestJson);
+    }
+    catch {
+        throw new Error('Container corrupt: manifest JSON parse failed');
+    }
+    return { manifest, dataOffset: manifestEnd };
+}
+/**
+ * Extract segment buffers from container data using manifest offsets.
+ */
+export function extractSegments(data, dataOffset, segments) {
+    const result = new Map();
+    for (const seg of segments) {
+        const start = dataOffset + seg.offset;
+        const end = start + seg.length;
+        if (end > data.length) {
+            throw new Error(`Segment '${seg.name}' extends beyond container data`);
+        }
+        result.set(seg.name, data.subarray(start, end));
+    }
+    return result;
+}
+//# sourceMappingURL=cognitive-container-codec.js.map