specmem-hardwicksoftware 3.5.99

package/dist/embeddings/projectionLayer.js

@@ -0,0 +1,345 @@
+/**
+ * FULLY DYNAMIC Embedding Projection Layer
+ *
+ * Projects embeddings between ANY dimensions - NO HARDCODED VALUES!
+ * ALL dimensions are fetched from database (pgvector table metadata).
+ *
+ * Uses random projection (Johnson-Lindenstrauss lemma) - no GPU needed!
+ *
+ * Why this works:
+ * - JL lemma proves random projections preserve pairwise distances
+ * - Higher dimensions = better separation for cosine similarity
+ * - Pre-computed matrix = zero training, instant deployment
+ *
+ * DATABASE IS THE SINGLE SOURCE OF TRUTH:
+ * - Source dimension: detected from input embedding vector
+ * - Target dimension: queried from memories table (pg_attribute.atttypmod)
+ *
+ * NO dimension constants, NO config file dimensions, NO hardcoded values!
+ *
+ * Performance: ~0.5ms per embedding on CPU
+ */
+import { logger } from '../utils/logger.js';
+import * as crypto from 'crypto';
+// Deterministic seed for reproducible projections
+const PROJECTION_SEED = 'specmem-embedding-projection-v1';
+const CACHE_TTL_MS = 60_000; // 60 seconds max cache
+let dimensionCache = {
+    sourceDim: null,
+    targetDim: null,
+    timestamp: 0
+};
+// Matrix cache (keyed by dimension pair for efficiency)
+const projectionMatrixCache = new Map();
+/**
+ * Query database for target embedding dimension
+ * Uses pg_attribute to get the actual vector dimension from memories table
+ *
+ * NOTE: pgvector stores dimension directly in atttypmod - NO -4 subtraction needed!
+ */
+async function queryDatabaseDimension(tableName = 'memories') {
+    try {
+        // Dynamic import to avoid circular dependencies
+        const { getDatabase } = await import('../database.js');
+        const db = getDatabase();
+        const result = await db.getTableDimension(tableName);
+        if (result !== null && result > 0) {
+            logger.debug({ tableName, dimension: result }, 'Queried dimension from database');
+        }
+        return result;
+    }
+    catch (error) {
+        logger.debug({ error }, 'Could not query database for dimension (may not be initialized yet)');
+        return null;
+    }
+}
+/**
+ * Get target dimension from database (with caching)
+ * This is THE dimension embeddings should be projected to.
+ * Returns null if database not available.
+ */
+export async function getTargetDimension() {
+    const now = Date.now();
+    // Return cached value if recent and valid
+    if (dimensionCache.targetDim !== null && (now - dimensionCache.timestamp) < CACHE_TTL_MS) {
+        return dimensionCache.targetDim;
+    }
+    // Query database for current dimension
+    const dbDim = await queryDatabaseDimension('memories');
+    if (dbDim !== null && dbDim > 0) {
+        dimensionCache.targetDim = dbDim;
+        dimensionCache.timestamp = now;
+        logger.info({ targetDim: dbDim }, 'Updated target dimension from database');
+    }
+    return dimensionCache.targetDim;
+}
+/**
+ * Synchronously get cached target dimension
+ * Returns cached value or null if not yet queried
+ *
+ * Use getTargetDimension() async version for guaranteed fresh value
+ */
+export function getCachedTargetDimension() {
+    const now = Date.now();
+    // Check if cache is stale
+    if (dimensionCache.targetDim !== null && (now - dimensionCache.timestamp) < CACHE_TTL_MS) {
+        return dimensionCache.targetDim;
+    }
+    // Cache is stale or empty
+    return dimensionCache.targetDim; // Still return it, but caller should prefer async version
+}
+/**
+ * Set target dimension (for use when dimension is known externally)
+ * Updates the cache - database remains source of truth
+ */
+export function setTargetDimension(dim) {
+    if (dim <= 0) {
+        logger.warn({ dim }, 'Invalid dimension, ignoring');
+        return;
+    }
+    dimensionCache.targetDim = dim;
+    dimensionCache.timestamp = Date.now();
+    logger.info({ targetDim: dim }, 'Set target dimension from external source');
+}
+/**
+ * Detect and cache source dimension from an embedding
+ */
+export function detectSourceDimension(embedding) {
+    const dim = embedding.length;
+    dimensionCache.sourceDim = dim;
+    logger.debug({ sourceDim: dim }, 'Detected source dimension from embedding');
+    return dim;
+}
+/**
+ * Clear dimension cache (forces re-fetch from database)
+ */
+export function clearDimensionCache() {
+    dimensionCache = { sourceDim: null, targetDim: null, timestamp: 0 };
+    projectionMatrixCache.clear();
+    logger.info('Dimension cache cleared');
+}
+/**
+ * Check if cache is stale
+ */
+export function isCacheStale() {
+    return (Date.now() - dimensionCache.timestamp) >= CACHE_TTL_MS;
+}
+/**
+ * Generate a deterministic random projection matrix
+ * Uses seeded RNG for reproducibility across restarts
+ */
+function generateProjectionMatrix(seed, inputDim, outputDim) {
+    const matrix = new Float32Array(inputDim * outputDim);
+    // Use hash-based seeding for deterministic random numbers
+    let hashState = crypto.createHash('sha256').update(seed).digest();
+    let hashIndex = 0;
+    const getNextRandom = () => {
+        if (hashIndex >= hashState.length - 4) {
+            // Rehash to get more random bytes
+            hashState = crypto.createHash('sha256').update(hashState).digest();
+            hashIndex = 0;
+        }
+        // Read 4 bytes as unsigned int, convert to 0-1 range
+        const value = hashState.readUInt32LE(hashIndex);
+        hashIndex += 4;
+        return value / 0xFFFFFFFF;
+    };
+    // Fill matrix with scaled random values
+    // Scale factor from JL lemma: sqrt(1/outputDim)
+    const scale = Math.sqrt(1.0 / outputDim);
+    for (let i = 0; i < inputDim * outputDim; i++) {
+        // Box-Muller transform for Gaussian distribution
+        const u1 = getNextRandom();
+        const u2 = getNextRandom();
+        const gaussian = Math.sqrt(-2 * Math.log(u1 + 1e-10)) * Math.cos(2 * Math.PI * u2);
+        matrix[i] = gaussian * scale;
+    }
+    return matrix;
+}
+/**
+ * Get or generate projection matrix for given dimensions
+ * Caches matrices by dimension pair for efficiency
+ */
+function getProjectionMatrix(inputDim, outputDim) {
+    const cacheKey = `${inputDim}x${outputDim}`;
+    let matrix = projectionMatrixCache.get(cacheKey);
+    if (!matrix) {
+        // Include dimensions in seed for determinism per dimension pair
+        const seed = `${PROJECTION_SEED}-${inputDim}-${outputDim}`;
+        logger.info({ inputDim, outputDim }, 'Generating projection matrix for new dimension pair');
+        matrix = generateProjectionMatrix(seed, inputDim, outputDim);
+        projectionMatrixCache.set(cacheKey, matrix);
+        logger.info({ inputDim, outputDim, cacheKey }, 'Projection matrix ready');
+    }
+    return matrix;
+}
+/**
+ * Core projection logic - projects embedding from any dimension to target dimension
+ * Uses JL random projection for expansion, averaging for contraction
+ */
+function projectEmbeddingCore(embedding, outputDim) {
+    const inputDim = embedding.length;
+    // Already at target dimension - return as-is
+    if (inputDim === outputDim) {
+        return embedding;
+    }
+    let result;
+    if (inputDim < outputDim) {
+        // EXPANSION: Use random projection matrix (JL lemma)
+        const matrix = getProjectionMatrix(inputDim, outputDim);
+        result = new Array(outputDim).fill(0);
+        // Matrix multiplication: result = embedding * matrix
+        for (let j = 0; j < outputDim; j++) {
+            let sum = 0;
+            for (let i = 0; i < inputDim; i++) {
+                sum += embedding[i] * matrix[i * outputDim + j];
+            }
+            result[j] = sum;
+        }
+    }
+    else {
+        // CONTRACTION: Use averaging (preserves information better than truncation)
+        result = new Array(outputDim).fill(0);
+        const ratio = inputDim / outputDim;
+        for (let i = 0; i < outputDim; i++) {
+            const start = Math.floor(i * ratio);
+            const end = Math.floor((i + 1) * ratio);
+            let sum = 0;
+            for (let j = start; j < end; j++) {
+                sum += embedding[j];
+            }
+            result[i] = sum / (end - start);
+        }
+    }
+    // L2 normalize the result (critical for cosine similarity!)
+    let norm = 0;
+    for (let i = 0; i < outputDim; i++) {
+        norm += result[i] * result[i];
+    }
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < outputDim; i++) {
+            result[i] /= norm;
+        }
+    }
+    return result;
+}
+/**
+ * Project embedding to target dimension (SYNC version)
+ * Uses cached target dimension or explicit dimension
+ *
+ * @param embedding - Input embedding vector (any dimension)
+ * @param targetDim - Optional explicit target dimension. If not provided, uses cached DB dimension.
+ * @returns Projected embedding at target dimension
+ */
+export function projectEmbedding(embedding, targetDim) {
+    const inputDim = embedding.length;
+    // Determine output dimension
+    let outputDim = targetDim;
+    if (outputDim === undefined || outputDim === null) {
+        outputDim = getCachedTargetDimension();
+        if (outputDim === null) {
+            // No cached dimension available - return embedding as-is
+            // Caller should use projectEmbeddingAsync for guaranteed dimension fetch
+            logger.debug({ inputDim }, 'No target dimension available, returning embedding as-is');
+            return embedding;
+        }
+    }
+    // Track source dimension
+    if (dimensionCache.sourceDim === null) {
+        dimensionCache.sourceDim = inputDim;
+    }
+    return projectEmbeddingCore(embedding, outputDim);
+}
+/**
+ * Project embedding to target dimension (ASYNC version)
+ * Queries database for target dimension if not cached
+ *
+ * @param embedding - Input embedding vector (any dimension)
+ * @returns Projected embedding at database target dimension
+ */
+export async function projectEmbeddingAsync(embedding) {
+    const targetDim = await getTargetDimension();
+    if (targetDim === null) {
+        logger.warn('Could not get target dimension from database, returning embedding as-is');
+        return embedding;
+    }
+    return projectEmbedding(embedding, targetDim);
+}
+/**
+ * Validate embedding matches expected dimension
+ * Returns true if valid, false if dimension mismatch
+ */
+export function validateEmbeddingDimension(embedding, expectedDim) {
+    const targetDim = expectedDim ?? getCachedTargetDimension();
+    if (targetDim === null) {
+        // Can't validate without target dimension - assume valid
+        return true;
+    }
+    return embedding.length === targetDim;
+}
+/**
+ * Batch project multiple embeddings (SYNC version)
+ */
+export function projectEmbeddingBatch(embeddings, targetDim) {
+    if (embeddings.length === 0)
+        return [];
+    return embeddings.map(e => projectEmbedding(e, targetDim));
+}
+/**
+ * Batch project multiple embeddings (ASYNC version)
+ * Queries database once for dimension, applies to all embeddings
+ */
+export async function projectEmbeddingBatchAsync(embeddings) {
+    if (embeddings.length === 0)
+        return [];
+    const targetDim = await getTargetDimension();
+    if (targetDim === null) {
+        logger.warn('Could not get target dimension from database, returning embeddings as-is');
+        return embeddings;
+    }
+    return embeddings.map(e => projectEmbedding(e, targetDim));
+}
+/**
+ * Get projection layer info (FULLY DYNAMIC)
+ * All dimensions come from runtime - no hardcoded values!
+ */
+export function getProjectionInfo() {
+    return {
+        sourceDim: dimensionCache.sourceDim,
+        targetDim: dimensionCache.targetDim,
+        method: 'random-projection-jl',
+        isDynamic: true,
+        cacheAgeMs: dimensionCache.timestamp > 0 ? Date.now() - dimensionCache.timestamp : -1,
+        isCacheStale: isCacheStale(),
+        matrixCacheSize: projectionMatrixCache.size
+    };
+}
+/**
+ * Get projection info (ASYNC version that queries database)
+ */
+export async function getProjectionInfoAsync() {
+    const targetDim = await getTargetDimension();
+    return {
+        sourceDim: dimensionCache.sourceDim,
+        targetDim,
+        method: 'random-projection-jl',
+        isDynamic: true,
+        fromDatabase: true
+    };
+}
+/**
+ * Pre-warm the dimension cache from database
+ * Call this after database is ready for optimal performance
+ */
+export async function warmDimensionCache() {
+    const targetDim = await getTargetDimension();
+    logger.info({ targetDim, sourceDim: dimensionCache.sourceDim }, 'Dimension cache warmed from database');
+    return {
+        sourceDim: dimensionCache.sourceDim,
+        targetDim
+    };
+}
+// NOTE: No pre-initialization or hardcoded dimensions!
+// All dimensions come from database at runtime.
+//# sourceMappingURL=projectionLayer.js.map

package/dist/embeddings/projectionLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionLayer.js","sourceRoot":"","sources":["../../src/embeddings/projectionLayer.ts"],"names":[],"mappings":"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"}

package/dist/events/Publisher.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Publisher.ts - LWJEB-inspired Event Publishing System
+ *
+ * Adapted from Hippo's LWJEB (https://github.com/Hippo/LWJEB)
+ * TypeScript implementation for SpecMem MCP
+ *
+ * Key features from LWJEB:
+ * - PubSub pattern with result caching
+ * - Async dispatcher threads (via setImmediate/setTimeout in JS)
+ * - WeakRef-based subscriber management
+ * - Sub-25ms dispatch latency target
+ *
+ * @author hardwicksoftwareservices (adapted from Hippo's Java implementation)
+ */
+import { EventEmitter } from 'events';
+import { EventBusConfiguration } from './config.js';
+import { PerformanceMetrics } from './metrics.js';
+/**
+ * Message handler function type
+ * Equivalent to LWJEB's MessageHandler<T>
+ */
+export type MessageHandler<T> = (topic: T) => void | Promise<void>;
+/**
+ * Handler registration with metadata
+ * Similar to LWJEB's wrapped handlers
+ */
+export interface RegisteredHandler<T> {
+    handler: MessageHandler<T>;
+    priority: number;
+    filter?: (topic: T) => boolean;
+    once: boolean;
+    subscriberId: string;
+}
+/**
+ * Publication result - equivalent to LWJEB's MessagePublicationResult<T>
+ * Gives control over how publications are handled
+ */
+export interface PublicationResult<T> {
+    topic: T;
+    handlers: RegisteredHandler<T>[];
+    timestamp: number;
+    /** Dispatch immediately on current tick */
+    dispatch(): Promise<DispatchResult>;
+    /** Queue for async dispatch */
+    async(): void;
+    /** Queue with timeout */
+    asyncWithTimeout(timeoutMs: number): void;
+}
+/**
+ * Result of dispatching an event
+ */
+export interface DispatchResult {
+    success: boolean;
+    handlersInvoked: number;
+    errors: Error[];
+    durationMs: number;
+}
+/**
+ * Dead message result - when no handlers exist
+ * Equivalent to LWJEB's DeadMessagePublicationResult
+ */
+export declare class DeadPublicationResult<T> implements PublicationResult<T> {
+    topic: T;
+    handlers: RegisteredHandler<T>[];
+    timestamp: number;
+    constructor(topic: T);
+    dispatch(): Promise<DispatchResult>;
+    async(): void;
+    asyncWithTimeout(_timeoutMs: number): void;
+}
+/**
+ * Standard publication result with handlers
+ * Equivalent to LWJEB's StandardMessagePublicationResult
+ */
+export declare class StandardPublicationResult<T> implements PublicationResult<T> {
+    topic: T;
+    handlers: RegisteredHandler<T>[];
+    timestamp: number;
+    private publisher;
+    private dispatched;
+    constructor(publisher: EventPublisher<T>, topic: T, handlers: RegisteredHandler<T>[]);
+    dispatch(): Promise<DispatchResult>;
+    async(): void;
+    asyncWithTimeout(timeoutMs: number): void;
+}
+/**
+ * EventPublisher - TypeScript adaptation of LWJEB's PubSub<T>
+ *
+ * Features:
+ * - Result caching for identical topics (performance optimization)
+ * - WeakRef subscriber management
+ * - Priority-based handler ordering
+ * - Filter support for selective handling
+ * - Performance metrics tracking
+ */
+export declare class EventPublisher<T = unknown> extends EventEmitter {
+    private config;
+    private metrics;
+    private subscriberMap;
+    private resultCache;
+    private dispatchQueue;
+    private isProcessingQueue;
+    private shutdown;
+    constructor(config?: Partial<EventBusConfiguration>);
+    /**
+     * Setup async dispatchers - equivalent to LWJEB's setupDispatchers()
+     * Uses setInterval instead of Java threads
+     */
+    private setupDispatchers;
+    /**
+     * Process the async dispatch queue
+     */
+    private processDispatchQueue;
+    /**
+     * Post/publish a topic - equivalent to LWJEB's post(T topic)
+     *
+     * Uses caching for performance: if we've seen this exact topic before
+     * and handlers haven't changed, return cached result
+     */
+    post(topic: T): PublicationResult<T>;
+    /**
+     * Subscribe a handler - equivalent to LWJEB's subscribe(Object parent)
+     */
+    subscribe(topicType: string, handler: MessageHandler<T>, options?: {
+        priority?: number;
+        filter?: (topic: T) => boolean;
+        once?: boolean;
+        subscriberId?: string;
+    }): void;
+    /**
+     * Subscribe once - handler is removed after first invocation
+     */
+    subscribeOnce(topicType: string, handler: MessageHandler<T>, options?: Omit<Parameters<typeof this.subscribe>[2], 'once'>): void;
+    /**
+     * Unsubscribe handlers - equivalent to LWJEB's unsubscribe(Object parent)
+     */
+    unsubscribe(topicType: string, subscriberId?: string): void;
+    /**
+     * Remove a specific handler registration
+     * Used internally for one-time handlers
+     */
+    removeHandler(registered: RegisteredHandler<T>): void;
+    /**
+     * Invalidate all caches - equivalent to LWJEB's invalidateCaches()
+     */
+    invalidateCaches(): void;
+    /**
+     * Add message to async dispatch queue
+     * Equivalent to LWJEB's addMessage()
+     */
+    addToQueue(result: PublicationResult<T>): void;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Get subscriber count for a topic type
+     */
+    getSubscriberCount(topicType: string): number;
+    /**
+     * Get all registered topic types
+     */
+    getTopicTypes(): string[];
+    /**
+     * Shutdown the publisher - equivalent to LWJEB's shutdown()
+     */
+    shutdownGracefully(timeoutMs?: number): Promise<void>;
+    /**
+     * Force immediate shutdown - equivalent to LWJEB's forceShutdown()
+     */
+    forceShutdown(): void;
+    /**
+     * Generate cache key for a topic
+     */
+    private generateCacheKey;
+    /**
+     * Get topic type identifier
+     */
+    private getTopicType;
+    /**
+     * Generate unique subscriber ID
+     */
+    private generateSubscriberId;
+}
+/**
+ * Create a new EventPublisher instance
+ * Factory function for convenience
+ */
+export declare function createPublisher<T = unknown>(config?: Partial<EventBusConfiguration>): EventPublisher<T>;
+export declare function getGlobalPublisher(): EventPublisher;
+export declare function resetGlobalPublisher(): void;
+export type { EventBusConfiguration } from './config.js';
+//# sourceMappingURL=Publisher.d.ts.map

package/dist/events/Publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Publisher.d.ts","sourceRoot":"","sources":["../../src/events/Publisher.ts"],"names":[],"mappings":"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"}