@ninebix/nmt-system 1.0.0

package/dist/events/event-bus.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Event Bus - Central event infrastructure for NMT system
+ *
+ * Provides publish/subscribe functionality for system-wide events,
+ * enabling loose coupling between modules.
+ *
+ * @module events/event-bus
+ */
+import { EventEmitter } from 'events';
+/**
+ * System event types
+ */
+export type SystemEventType = 'neuron:created' | 'neuron:updated' | 'neuron:deleted' | 'synapse:formed' | 'synapse:updated' | 'synapse:removed' | 'merkle:root_changed' | 'merkle:proof_generated' | 'merkle:verified' | 'learning:session_started' | 'learning:session_ended' | 'learning:extract' | 'learning:pattern' | 'learning:process' | 'learning:outcome' | 'learning:progress' | 'learning:complete' | 'learning:error' | 'sync:state_changed' | 'sync:conflict' | 'sync:resolved' | 'sync:peer_connected' | 'sync:peer_disconnected' | 'attractor:created' | 'attractor:decayed' | 'attractor:activated' | 'evolution:started' | 'evolution:completed' | 'evolution:neuron_evolved';
+/**
+ * System event structure
+ */
+export interface SystemEvent<T = unknown> {
+    /** Event type */
+    type: SystemEventType;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Source module/component */
+    source: string;
+    /** Optional correlation ID for tracking related events */
+    correlationId?: string;
+    /** Event payload */
+    payload: T;
+}
+/**
+ * Event handler function type
+ */
+export type EventHandler<T = unknown> = (event: SystemEvent<T>) => void | Promise<void>;
+/**
+ * Event filter options
+ */
+export interface EventFilter {
+    /** Filter by event type(s) */
+    types?: SystemEventType[];
+    /** Filter by source */
+    source?: string;
+    /** Filter by correlation ID */
+    correlationId?: string;
+    /** Filter events after this timestamp */
+    after?: string;
+    /** Filter events before this timestamp */
+    before?: string;
+}
+/**
+ * EventBus - Central event hub for the NMT system
+ *
+ * Features:
+ * - Type-safe publish/subscribe
+ * - Event history with configurable retention
+ * - Event filtering and querying
+ * - Async handler support
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to events
+ * bus.subscribe('learning:progress', (event) => {
+ *   console.log(`Progress: ${event.payload.current}/${event.payload.total}`);
+ * });
+ *
+ * // Publish an event
+ * bus.publish({
+ *   type: 'learning:progress',
+ *   timestamp: new Date().toISOString(),
+ *   source: 'learning-system',
+ *   payload: { stage: 'extract', current: 5, total: 10 }
+ * });
+ * ```
+ */
+/**
+ * EventBus configuration options
+ */
+export interface EventBusOptions {
+    /** Maximum number of events to retain in history (default: 1000) */
+    maxHistory?: number;
+    /** Enable event history retention (default: true) */
+    enableHistory?: boolean;
+    /** Maximum payload size in bytes (default: 1MB) */
+    maxPayloadSize?: number;
+    /** Default timeout for waitFor() in ms (default: 30000) */
+    defaultWaitTimeout?: number;
+}
+export declare class EventBus extends EventEmitter {
+    private eventHistory;
+    private maxHistory;
+    private historyEnabled;
+    private maxPayloadSize;
+    private defaultWaitTimeout;
+    constructor(options?: EventBusOptions);
+    /**
+     * Publish an event to all subscribers
+     * @throws {Error} If payload exceeds maximum size limit
+     */
+    publish<T>(event: SystemEvent<T>): void;
+    /**
+     * Subscribe to a specific event type
+     */
+    subscribe<T>(type: SystemEventType | '*', handler: EventHandler<T>): () => void;
+    /**
+     * Subscribe to multiple event types
+     */
+    subscribeMany<T>(types: SystemEventType[], handler: EventHandler<T>): () => void;
+    /**
+     * Subscribe once - handler will be called at most once
+     */
+    subscribeOnce<T>(type: SystemEventType, handler: EventHandler<T>): () => void;
+    /**
+     * Get events since a specific timestamp
+     */
+    getEventsSince(timestamp: string): SystemEvent[];
+    /**
+     * Get events matching a filter
+     */
+    getEvents(filter?: EventFilter): SystemEvent[];
+    /**
+     * Get the most recent N events
+     */
+    getRecentEvents(count: number): SystemEvent[];
+    /**
+     * Get events by correlation ID
+     */
+    getCorrelatedEvents(correlationId: string): SystemEvent[];
+    /**
+     * Clear event history
+     */
+    clearHistory(): void;
+    /**
+     * Get history statistics
+     */
+    getStats(): {
+        totalEvents: number;
+        eventsByType: Record<string, number>;
+        oldestEvent: string | null;
+        newestEvent: string | null;
+    };
+    /**
+     * Wait for a specific event (with timeout protection)
+     * @param type - Event type to wait for
+     * @param options - Wait options including timeout and filter
+     * @returns Promise that resolves with the matching event
+     * @throws {Error} If timeout is exceeded (default: 30 seconds)
+     */
+    waitFor<T>(type: SystemEventType, options?: {
+        timeout?: number;
+        filter?: (event: SystemEvent<T>) => boolean;
+    }): Promise<SystemEvent<T>>;
+    /**
+     * Create a child bus that forwards events to this bus
+     */
+    createChild(sourcePrefix: string): EventBus;
+}
+export declare function getEventBus(): EventBus;
+/**
+ * Reset the global EventBus (mainly for testing)
+ */
+export declare function resetEventBus(): void;
+/**
+ * Helper to create a typed event
+ */
+export declare function createEvent<T>(type: SystemEventType, source: string, payload: T, correlationId?: string): SystemEvent<T>;
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/events/event-bus.d.ts.map

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

package/dist/events/event-bus.js

@@ -0,0 +1,228 @@
+/**
+ * Event Bus - Central event infrastructure for NMT system
+ *
+ * Provides publish/subscribe functionality for system-wide events,
+ * enabling loose coupling between modules.
+ *
+ * @module events/event-bus
+ */
+import { EventEmitter } from 'events';
+export class EventBus extends EventEmitter {
+    eventHistory = [];
+    maxHistory;
+    historyEnabled;
+    maxPayloadSize;
+    defaultWaitTimeout;
+    constructor(options) {
+        super();
+        this.maxHistory = options?.maxHistory ?? 1000;
+        this.historyEnabled = options?.enableHistory ?? true;
+        this.maxPayloadSize = options?.maxPayloadSize ?? 1_000_000; // 1MB default
+        this.defaultWaitTimeout = options?.defaultWaitTimeout ?? 30000; // 30 seconds
+        this.setMaxListeners(100);
+    }
+    /**
+     * Publish an event to all subscribers
+     * @throws {Error} If payload exceeds maximum size limit
+     */
+    publish(event) {
+        // Validate payload size to prevent DoS
+        const payloadStr = JSON.stringify(event.payload);
+        if (payloadStr.length > this.maxPayloadSize) {
+            throw new Error(`Event payload exceeds maximum size (${payloadStr.length} > ${this.maxPayloadSize} bytes)`);
+        }
+        // Add to history if enabled
+        if (this.historyEnabled) {
+            this.eventHistory.push(event);
+            // Trim history efficiently using splice (avoids creating new array)
+            if (this.eventHistory.length > this.maxHistory) {
+                this.eventHistory.splice(0, this.eventHistory.length - this.maxHistory);
+            }
+        }
+        // Emit to type-specific listeners
+        this.emit(event.type, event);
+        // Emit to wildcard listeners
+        this.emit('*', event);
+    }
+    /**
+     * Subscribe to a specific event type
+     */
+    subscribe(type, handler) {
+        this.on(type, handler);
+        // Return unsubscribe function
+        return () => {
+            this.off(type, handler);
+        };
+    }
+    /**
+     * Subscribe to multiple event types
+     */
+    subscribeMany(types, handler) {
+        const unsubscribers = types.map(type => this.subscribe(type, handler));
+        return () => {
+            unsubscribers.forEach(unsub => unsub());
+        };
+    }
+    /**
+     * Subscribe once - handler will be called at most once
+     */
+    subscribeOnce(type, handler) {
+        const wrappedHandler = (event) => {
+            this.off(type, wrappedHandler);
+            return handler(event);
+        };
+        this.on(type, wrappedHandler);
+        return () => {
+            this.off(type, wrappedHandler);
+        };
+    }
+    /**
+     * Get events since a specific timestamp
+     */
+    getEventsSince(timestamp) {
+        const cutoff = new Date(timestamp).getTime();
+        return this.eventHistory.filter(event => new Date(event.timestamp).getTime() >= cutoff);
+    }
+    /**
+     * Get events matching a filter
+     */
+    getEvents(filter) {
+        if (!filter) {
+            return [...this.eventHistory];
+        }
+        return this.eventHistory.filter(event => {
+            // Type filter
+            if (filter.types && !filter.types.includes(event.type)) {
+                return false;
+            }
+            // Source filter
+            if (filter.source && event.source !== filter.source) {
+                return false;
+            }
+            // Correlation ID filter
+            if (filter.correlationId && event.correlationId !== filter.correlationId) {
+                return false;
+            }
+            // Time range filter
+            const eventTime = new Date(event.timestamp).getTime();
+            if (filter.after && eventTime < new Date(filter.after).getTime()) {
+                return false;
+            }
+            if (filter.before && eventTime > new Date(filter.before).getTime()) {
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Get the most recent N events
+     */
+    getRecentEvents(count) {
+        return this.eventHistory.slice(-count);
+    }
+    /**
+     * Get events by correlation ID
+     */
+    getCorrelatedEvents(correlationId) {
+        return this.eventHistory.filter(event => event.correlationId === correlationId);
+    }
+    /**
+     * Clear event history
+     */
+    clearHistory() {
+        this.eventHistory = [];
+    }
+    /**
+     * Get history statistics
+     */
+    getStats() {
+        const eventsByType = {};
+        for (const event of this.eventHistory) {
+            eventsByType[event.type] = (eventsByType[event.type] || 0) + 1;
+        }
+        return {
+            totalEvents: this.eventHistory.length,
+            eventsByType,
+            oldestEvent: this.eventHistory[0]?.timestamp ?? null,
+            newestEvent: this.eventHistory[this.eventHistory.length - 1]?.timestamp ?? null,
+        };
+    }
+    /**
+     * Wait for a specific event (with timeout protection)
+     * @param type - Event type to wait for
+     * @param options - Wait options including timeout and filter
+     * @returns Promise that resolves with the matching event
+     * @throws {Error} If timeout is exceeded (default: 30 seconds)
+     */
+    waitFor(type, options) {
+        return new Promise((resolve, reject) => {
+            // Always use a timeout to prevent infinite waits
+            const effectiveTimeout = options?.timeout ?? this.defaultWaitTimeout;
+            const handler = (event) => {
+                // Apply custom filter if provided
+                if (options?.filter && !options.filter(event)) {
+                    return;
+                }
+                clearTimeout(timeoutId);
+                this.off(type, handler);
+                resolve(event);
+            };
+            this.on(type, handler);
+            // Set timeout (always, to prevent infinite waits)
+            const timeoutId = setTimeout(() => {
+                this.off(type, handler);
+                reject(new Error(`Timeout waiting for event: ${type} (${effectiveTimeout}ms)`));
+            }, effectiveTimeout);
+        });
+    }
+    /**
+     * Create a child bus that forwards events to this bus
+     */
+    createChild(sourcePrefix) {
+        const child = new EventBus({
+            maxHistory: this.maxHistory,
+            enableHistory: false // Child doesn't maintain its own history
+        });
+        // Forward all events to parent with modified source
+        child.subscribe('*', (event) => {
+            this.publish({
+                ...event,
+                source: `${sourcePrefix}/${event.source}`,
+            });
+        });
+        return child;
+    }
+}
+/**
+ * Create a singleton EventBus instance
+ */
+let globalEventBus = null;
+export function getEventBus() {
+    if (!globalEventBus) {
+        globalEventBus = new EventBus();
+    }
+    return globalEventBus;
+}
+/**
+ * Reset the global EventBus (mainly for testing)
+ */
+export function resetEventBus() {
+    if (globalEventBus) {
+        globalEventBus.removeAllListeners();
+        globalEventBus.clearHistory();
+        globalEventBus = null;
+    }
+}
+/**
+ * Helper to create a typed event
+ */
+export function createEvent(type, source, payload, correlationId) {
+    return {
+        type,
+        timestamp: new Date().toISOString(),
+        source,
+        correlationId,
+        payload,
+    };
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/events/event-bus.js.map

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

package/dist/events/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Events module - Central event infrastructure
+ * @module events
+ */
+export { EventBus, getEventBus, resetEventBus, createEvent, type SystemEventType, type SystemEvent, type EventHandler, type EventFilter, } from './event-bus.js';
+export { ProgressTracker, createProgressTracker, getProgressTracker, resetProgressTracker, type ProgressState, type ProgressEventPayload, type ProgressTrackerOptions, } from './progress-tracker.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC"}

package/dist/events/index.js

@@ -0,0 +1,7 @@
+/**
+ * Events module - Central event infrastructure
+ * @module events
+ */
+export { EventBus, getEventBus, resetEventBus, createEvent, } from './event-bus.js';
+export { ProgressTracker, createProgressTracker, getProgressTracker, resetProgressTracker, } from './progress-tracker.js';
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,WAAW,GAKZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,GAIrB,MAAM,uBAAuB,CAAC"}

package/dist/events/progress-tracker.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Progress Tracker - Real-time progress tracking with ETA calculation
+ *
+ * Provides progress monitoring for long-running operations like learning sessions.
+ *
+ * @module events/progress-tracker
+ */
+import type { UUID } from '../types/index.js';
+import { EventBus } from './event-bus.js';
+/**
+ * Progress state for a tracked operation
+ */
+export interface ProgressState {
+    /** Unique session/operation ID */
+    sessionId: UUID;
+    /** Current stage name */
+    stage: string;
+    /** Number of items processed */
+    current: number;
+    /** Total items to process */
+    total: number;
+    /** Start time (ms since epoch) */
+    startTime: number;
+    /** Last update time (ms since epoch) */
+    lastUpdateTime: number;
+    /** Items processed per second */
+    throughput: number;
+    /** Estimated time remaining (ms) */
+    eta: number;
+    /** Progress percentage (0-100) */
+    percentage: number;
+    /** Optional status message */
+    message?: string;
+}
+/**
+ * Progress update event payload
+ */
+export interface ProgressEventPayload {
+    sessionId: UUID;
+    stage: string;
+    current: number;
+    total: number;
+    percentage: number;
+    throughput: number;
+    eta: number;
+    message?: string;
+}
+/**
+ * Progress tracker options
+ */
+export interface ProgressTrackerOptions {
+    /** EventBus for publishing events */
+    eventBus?: EventBus;
+    /** Minimum interval between progress events (ms) */
+    throttleInterval?: number;
+    /** Enable automatic ETA smoothing */
+    smoothEta?: boolean;
+}
+/**
+ * ProgressTracker - Track and report progress of long-running operations
+ *
+ * Features:
+ * - Real-time progress updates
+ * - Throughput calculation (items/sec)
+ * - ETA estimation with smoothing
+ * - Multi-stage tracking
+ * - Throttled event emission
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ProgressTracker({ eventBus });
+ *
+ * // Start tracking
+ * tracker.startTracking('session-123', 'processing', 100);
+ *
+ * // Update progress
+ * for (let i = 0; i < 100; i++) {
+ *   await processItem(i);
+ *   tracker.updateProgress('session-123', i + 1);
+ * }
+ *
+ * // End tracking
+ * const finalState = tracker.endTracking('session-123');
+ * console.log(`Completed in ${finalState.throughput.toFixed(2)} items/sec`);
+ * ```
+ */
+export declare class ProgressTracker {
+    private sessions;
+    private eventBus;
+    private throttleInterval;
+    private smoothEta;
+    private lastEmitTime;
+    private etaHistory;
+    constructor(options?: ProgressTrackerOptions);
+    /**
+     * Start tracking progress for a session
+     */
+    startTracking(sessionId: UUID, stage: string, total: number, message?: string): ProgressState;
+    /**
+     * Update progress for a session
+     */
+    updateProgress(sessionId: UUID, current: number, message?: string): ProgressState | null;
+    /**
+     * Change the current stage
+     */
+    changeStage(sessionId: UUID, newStage: string, total: number, message?: string): ProgressState | null;
+    /**
+     * End tracking for a session
+     */
+    endTracking(sessionId: UUID): ProgressState | null;
+    /**
+     * Get current progress for a session
+     */
+    getProgress(sessionId: UUID): ProgressState | null;
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions(): UUID[];
+    /**
+     * Check if a session is being tracked
+     */
+    isTracking(sessionId: UUID): boolean;
+    /**
+     * Calculate ETA for a session
+     */
+    calculateETA(sessionId: UUID): number;
+    /**
+     * Get formatted time remaining
+     */
+    getFormattedETA(sessionId: UUID): string;
+    /**
+     * Set the event bus (for deferred initialization)
+     */
+    setEventBus(eventBus: EventBus): void;
+    /**
+     * Calculate smoothed ETA using exponential moving average
+     */
+    private calculateSmoothedEta;
+    /**
+     * Emit progress event (with throttling)
+     */
+    private emitProgressEvent;
+}
+/**
+ * Create a progress tracker instance
+ */
+export declare function createProgressTracker(options?: ProgressTrackerOptions): ProgressTracker;
+export declare function getProgressTracker(): ProgressTracker;
+export declare function resetProgressTracker(): void;
+//# sourceMappingURL=progress-tracker.d.ts.map

package/dist/events/progress-tracker.d.ts.map

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