@agentic-qe/v3 3.0.0-alpha.3

package/src/kernel/interfaces.ts

@@ -0,0 +1,257 @@
+/**
+ * Agentic QE v3 - Kernel Interfaces
+ * Core interfaces for the microkernel architecture
+ */
+
+import {
+  DomainName,
+  DomainEvent,
+  EventHandler,
+  Result,
+  AgentStatus,
+  Disposable,
+  Initializable,
+} from '../shared/types';
+
+// ============================================================================
+// Domain Plugin Interface
+// ============================================================================
+
+export interface DomainPlugin extends Initializable, Disposable {
+  /** Unique domain identifier */
+  readonly name: DomainName;
+
+  /** Domain version */
+  readonly version: string;
+
+  /** Domain dependencies */
+  readonly dependencies: DomainName[];
+
+  /** Check if domain is ready */
+  isReady(): boolean;
+
+  /** Get domain health status */
+  getHealth(): DomainHealth;
+
+  /** Handle incoming domain events */
+  handleEvent(event: DomainEvent): Promise<void>;
+
+  /** Get domain's public API */
+  getAPI<T>(): T;
+}
+
+export interface DomainHealth {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  agents: {
+    total: number;
+    active: number;
+    idle: number;
+    failed: number;
+  };
+  lastActivity?: Date;
+  errors: string[];
+}
+
+// ============================================================================
+// Event Bus Interface
+// ============================================================================
+
+export interface EventBus extends Disposable {
+  /** Publish an event to all subscribers */
+  publish<T>(event: DomainEvent<T>): Promise<void>;
+
+  /** Subscribe to events of a specific type */
+  subscribe<T>(eventType: string, handler: EventHandler<T>): Subscription;
+
+  /** Subscribe to all events from a domain */
+  subscribeToChannel(domain: DomainName, handler: EventHandler): Subscription;
+
+  /** Get event history (for replay) */
+  getHistory(filter?: EventFilter): Promise<DomainEvent[]>;
+}
+
+export interface Subscription {
+  unsubscribe(): void;
+  readonly active: boolean;
+}
+
+export interface EventFilter {
+  eventTypes?: string[];
+  sources?: DomainName[];
+  fromTimestamp?: Date;
+  toTimestamp?: Date;
+  correlationId?: string;
+  limit?: number;
+}
+
+// ============================================================================
+// Agent Coordinator Interface
+// ============================================================================
+
+export interface AgentCoordinator extends Disposable {
+  /** Spawn a new agent */
+  spawn(config: AgentSpawnConfig): Promise<Result<string, Error>>;
+
+  /** Get agent status */
+  getStatus(agentId: string): AgentStatus | undefined;
+
+  /** List all agents */
+  listAgents(filter?: AgentFilter): AgentInfo[];
+
+  /** Stop an agent */
+  stop(agentId: string): Promise<Result<void, Error>>;
+
+  /** Get current agent count */
+  getActiveCount(): number;
+
+  /** Check if can spawn more agents */
+  canSpawn(): boolean;
+}
+
+export interface AgentSpawnConfig {
+  name: string;
+  domain: DomainName;
+  type: string;
+  capabilities: string[];
+  config?: Record<string, unknown>;
+}
+
+export interface AgentFilter {
+  domain?: DomainName;
+  status?: AgentStatus;
+  type?: string;
+}
+
+export interface AgentInfo {
+  id: string;
+  name: string;
+  domain: DomainName;
+  type: string;
+  status: AgentStatus;
+  startedAt?: Date;
+}
+
+// ============================================================================
+// Plugin Loader Interface
+// ============================================================================
+
+export interface PluginLoader {
+  /** Load a domain plugin */
+  load(domain: DomainName): Promise<DomainPlugin>;
+
+  /** Unload a domain plugin */
+  unload(domain: DomainName): Promise<void>;
+
+  /** Check if domain is loaded */
+  isLoaded(domain: DomainName): boolean;
+
+  /** Get loaded domains */
+  getLoaded(): DomainName[];
+
+  /** Load all domains */
+  loadAll(): Promise<void>;
+}
+
+// ============================================================================
+// Memory Backend Interface
+// ============================================================================
+
+export interface MemoryBackend extends Initializable, Disposable {
+  /** Store a value */
+  set<T>(key: string, value: T, options?: StoreOptions): Promise<void>;
+
+  /** Retrieve a value */
+  get<T>(key: string): Promise<T | undefined>;
+
+  /** Delete a value */
+  delete(key: string): Promise<boolean>;
+
+  /** Check if key exists */
+  has(key: string): Promise<boolean>;
+
+  /** Search by pattern */
+  search(pattern: string, limit?: number): Promise<string[]>;
+
+  /** Vector similarity search (HNSW) */
+  vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]>;
+
+  /** Store vector embedding */
+  storeVector(key: string, embedding: number[], metadata?: unknown): Promise<void>;
+}
+
+export interface StoreOptions {
+  ttl?: number;
+  namespace?: string;
+  persist?: boolean;
+}
+
+export interface VectorSearchResult {
+  key: string;
+  score: number;
+  metadata?: unknown;
+}
+
+// ============================================================================
+// Kernel Interface
+// ============================================================================
+
+export interface QEKernel extends Initializable, Disposable {
+  /** Get the event bus */
+  readonly eventBus: EventBus;
+
+  /** Get the agent coordinator */
+  readonly coordinator: AgentCoordinator;
+
+  /** Get the plugin loader */
+  readonly plugins: PluginLoader;
+
+  /** Get the memory backend */
+  readonly memory: MemoryBackend;
+
+  /** Get a domain's API (synchronous, returns undefined if not loaded) */
+  getDomainAPI<T>(domain: DomainName): T | undefined;
+
+  /** Get a domain's API with lazy loading support */
+  getDomainAPIAsync?<T>(domain: DomainName): Promise<T | undefined>;
+
+  /** Ensure a domain is loaded */
+  ensureDomainLoaded?(domain: DomainName): Promise<boolean>;
+
+  /** Check if a domain is currently loaded */
+  isDomainLoaded?(domain: DomainName): boolean;
+
+  /** Get list of loaded domains */
+  getLoadedDomains?(): DomainName[];
+
+  /** Get list of enabled but not yet loaded domains */
+  getPendingDomains?(): DomainName[];
+
+  /** Get kernel health */
+  getHealth(): KernelHealth;
+
+  /** Get kernel configuration */
+  getConfig(): KernelConfig;
+}
+
+export interface KernelHealth {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  uptime: number;
+  domains: Record<DomainName, DomainHealth>;
+  agents: {
+    total: number;
+    active: number;
+    maxAllowed: number;
+  };
+  memory: {
+    used: number;
+    available: number;
+  };
+}
+
+export interface KernelConfig {
+  maxConcurrentAgents: number;
+  memoryBackend: 'sqlite' | 'agentdb' | 'hybrid';
+  hnswEnabled: boolean;
+  lazyLoading: boolean;
+  enabledDomains: DomainName[];
+}

package/src/kernel/kernel.ts

@@ -0,0 +1,285 @@
+/**
+ * Agentic QE v3 - QE Kernel
+ * Microkernel implementation coordinating all domains
+ */
+
+import { DomainName, ALL_DOMAINS } from '../shared/types';
+import {
+  QEKernel,
+  EventBus,
+  AgentCoordinator,
+  PluginLoader,
+  MemoryBackend,
+  KernelHealth,
+  KernelConfig,
+  DomainHealth,
+} from './interfaces';
+import { InMemoryEventBus } from './event-bus';
+import { DefaultAgentCoordinator } from './agent-coordinator';
+import { DefaultPluginLoader } from './plugin-loader';
+import { InMemoryBackend } from './memory-backend';
+
+// Import domain plugin factories
+import { createTestGenerationPlugin } from '../domains/test-generation/plugin';
+import { createTestExecutionPlugin } from '../domains/test-execution/plugin';
+import { createCoverageAnalysisPlugin } from '../domains/coverage-analysis/plugin';
+import { createQualityAssessmentPlugin } from '../domains/quality-assessment/plugin';
+import { createDefectIntelligencePlugin } from '../domains/defect-intelligence/plugin';
+import { createRequirementsValidationPlugin } from '../domains/requirements-validation/plugin';
+import { createCodeIntelligencePlugin } from '../domains/code-intelligence/plugin';
+import { createSecurityCompliancePlugin } from '../domains/security-compliance/plugin';
+import { createContractTestingPlugin } from '../domains/contract-testing/plugin';
+import { createVisualAccessibilityPlugin } from '../domains/visual-accessibility/plugin';
+import { createChaosResiliencePlugin } from '../domains/chaos-resilience/plugin';
+import { createLearningOptimizationPlugin } from '../domains/learning-optimization/plugin';
+
+// Domain factory map - returns plugin instances (not Promises)
+type PluginFactoryFn = (eventBus: EventBus, memory: MemoryBackend, coordinator: AgentCoordinator) => import('./interfaces').DomainPlugin;
+
+const DOMAIN_FACTORIES: Record<DomainName, PluginFactoryFn> = {
+  'test-generation': (eb, m, c) => createTestGenerationPlugin(eb, m, c),
+  'test-execution': (eb, m) => createTestExecutionPlugin(eb, m),
+  'coverage-analysis': (eb, m) => createCoverageAnalysisPlugin(eb, m),
+  'quality-assessment': (eb, m, c) => createQualityAssessmentPlugin(eb, m, c),
+  'defect-intelligence': (eb, m, c) => createDefectIntelligencePlugin(eb, m, c),
+  'requirements-validation': (eb, m, c) => createRequirementsValidationPlugin(eb, m, c),
+  'code-intelligence': (eb, m, c) => createCodeIntelligencePlugin(eb, m, c),
+  'security-compliance': (eb, m, c) => createSecurityCompliancePlugin(eb, m, c),
+  'contract-testing': (eb, m, c) => createContractTestingPlugin(eb, m, c),
+  'visual-accessibility': (eb, m, c) => createVisualAccessibilityPlugin(eb, m, c),
+  'chaos-resilience': (eb, m, c) => createChaosResiliencePlugin(eb, m, c),
+  'learning-optimization': (eb, m, c) => createLearningOptimizationPlugin(eb, m, c),
+};
+
+const DEFAULT_CONFIG: KernelConfig = {
+  maxConcurrentAgents: 15,
+  memoryBackend: 'hybrid',
+  hnswEnabled: true,
+  lazyLoading: true,
+  enabledDomains: [...ALL_DOMAINS],
+};
+
+export class QEKernelImpl implements QEKernel {
+  private _eventBus: EventBus;
+  private _coordinator: AgentCoordinator;
+  private _plugins: PluginLoader;
+  private _memory: MemoryBackend;
+  private _config: KernelConfig;
+  private _startTime: Date;
+  private _initialized = false;
+
+  constructor(config: Partial<KernelConfig> = {}) {
+    this._config = { ...DEFAULT_CONFIG, ...config };
+    this._startTime = new Date();
+
+    // Initialize core components
+    this._memory = new InMemoryBackend();
+    this._eventBus = new InMemoryEventBus();
+    this._coordinator = new DefaultAgentCoordinator(this._config.maxConcurrentAgents);
+    this._plugins = new DefaultPluginLoader(
+      this._eventBus,
+      this._memory,
+      this._config.lazyLoading
+    );
+
+    // Register domain factories for enabled domains
+    for (const domain of this._config.enabledDomains) {
+      const factory = DOMAIN_FACTORIES[domain];
+      if (factory) {
+        // Wrap factory to match PluginLoader signature (async)
+        (this._plugins as DefaultPluginLoader).registerFactory(
+          domain,
+          async (eventBus: EventBus, memory: MemoryBackend) => {
+            // Create plugin synchronously, return as Promise
+            return Promise.resolve(factory(eventBus, memory, this._coordinator));
+          }
+        );
+      }
+    }
+  }
+
+  get eventBus(): EventBus {
+    return this._eventBus;
+  }
+
+  get coordinator(): AgentCoordinator {
+    return this._coordinator;
+  }
+
+  get plugins(): PluginLoader {
+    return this._plugins;
+  }
+
+  get memory(): MemoryBackend {
+    return this._memory;
+  }
+
+  async initialize(): Promise<void> {
+    if (this._initialized) {
+      return;
+    }
+
+    // Initialize memory backend
+    await this._memory.initialize();
+
+    // Load plugins based on configuration
+    if (!this._config.lazyLoading) {
+      await this._plugins.loadAll();
+    }
+
+    this._initialized = true;
+  }
+
+  async dispose(): Promise<void> {
+    // Dispose in reverse order of initialization
+    await (this._plugins as DefaultPluginLoader).disposeAll();
+    await this._coordinator.dispose();
+    await this._eventBus.dispose();
+    await this._memory.dispose();
+
+    this._initialized = false;
+  }
+
+  getDomainAPI<T>(domain: DomainName): T | undefined {
+    const plugin = (this._plugins as DefaultPluginLoader).getPlugin(domain);
+    return plugin?.getAPI<T>();
+  }
+
+  /**
+   * Get domain API with lazy loading support
+   * Will load the domain if not already loaded and lazy loading is enabled
+   */
+  async getDomainAPIAsync<T>(domain: DomainName): Promise<T | undefined> {
+    // Check if already loaded
+    let plugin = (this._plugins as DefaultPluginLoader).getPlugin(domain);
+
+    // Lazy load if enabled and domain not yet loaded
+    if (!plugin && this._config.lazyLoading && this._config.enabledDomains.includes(domain)) {
+      try {
+        plugin = await this._plugins.load(domain);
+      } catch (error) {
+        console.error(`[QEKernel] Failed to lazy load domain ${domain}:`, error);
+        return undefined;
+      }
+    }
+
+    return plugin?.getAPI<T>();
+  }
+
+  /**
+   * Ensure a domain is loaded (for lazy loading scenarios)
+   * Returns true if the domain is now loaded, false otherwise
+   */
+  async ensureDomainLoaded(domain: DomainName): Promise<boolean> {
+    if (this._plugins.isLoaded(domain)) {
+      return true;
+    }
+
+    if (!this._config.enabledDomains.includes(domain)) {
+      console.warn(`[QEKernel] Domain ${domain} is not enabled`);
+      return false;
+    }
+
+    try {
+      await this._plugins.load(domain);
+      return true;
+    } catch (error) {
+      console.error(`[QEKernel] Failed to load domain ${domain}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if a domain is currently loaded
+   */
+  isDomainLoaded(domain: DomainName): boolean {
+    return this._plugins.isLoaded(domain);
+  }
+
+  /**
+   * Get list of loaded domains
+   */
+  getLoadedDomains(): DomainName[] {
+    return this._plugins.getLoaded();
+  }
+
+  /**
+   * Get list of enabled but not yet loaded domains
+   */
+  getPendingDomains(): DomainName[] {
+    const loaded = new Set(this._plugins.getLoaded());
+    return this._config.enabledDomains.filter(d => !loaded.has(d));
+  }
+
+  getHealth(): KernelHealth {
+    const agentList = this._coordinator.listAgents();
+    const domains: Record<string, DomainHealth> = {};
+
+    // Get health for loaded domains
+    for (const domain of this._plugins.getLoaded()) {
+      const plugin = (this._plugins as DefaultPluginLoader).getPlugin(domain);
+      if (plugin) {
+        domains[domain] = plugin.getHealth();
+      }
+    }
+
+    // Add status for unloaded domains (lazy loading aware)
+    for (const domain of ALL_DOMAINS) {
+      if (!domains[domain]) {
+        const isEnabled = this._config.enabledDomains.includes(domain);
+        const canLazyLoad = this._config.lazyLoading && isEnabled;
+
+        domains[domain] = {
+          status: canLazyLoad ? 'healthy' : (isEnabled ? 'degraded' : 'healthy'),
+          agents: { total: 0, active: 0, idle: 0, failed: 0 },
+          errors: canLazyLoad
+            ? []
+            : (isEnabled ? ['Domain not yet loaded'] : []),
+          // Mark as not loaded for lazy loading awareness
+          ...({ loaded: false, lazyLoadable: canLazyLoad } as Partial<DomainHealth>),
+        };
+      }
+    }
+
+    const activeCount = this._coordinator.getActiveCount();
+    const memStats = (this._memory as InMemoryBackend).getStats();
+
+    return {
+      status: this.determineOverallStatus(domains),
+      uptime: Date.now() - this._startTime.getTime(),
+      domains: domains as Record<DomainName, DomainHealth>,
+      agents: {
+        total: agentList.length,
+        active: activeCount,
+        maxAllowed: this._config.maxConcurrentAgents,
+      },
+      memory: {
+        used: memStats.entries + memStats.vectors,
+        available: Number.MAX_SAFE_INTEGER, // In-memory has no limit
+      },
+    };
+  }
+
+  private determineOverallStatus(
+    domains: Record<string, DomainHealth>
+  ): 'healthy' | 'degraded' | 'unhealthy' {
+    const statuses = Object.values(domains).map((d) => d.status);
+
+    if (statuses.some((s) => s === 'unhealthy')) {
+      return 'unhealthy';
+    }
+    if (statuses.some((s) => s === 'degraded')) {
+      return 'degraded';
+    }
+    return 'healthy';
+  }
+
+  getConfig(): KernelConfig {
+    return { ...this._config };
+  }
+}
+
+// Factory function
+export function createKernel(config?: Partial<KernelConfig>): QEKernel {
+  return new QEKernelImpl(config);
+}

package/src/kernel/memory-backend.ts

@@ -0,0 +1,169 @@
+/**
+ * Agentic QE v3 - Memory Backend
+ * Hybrid memory implementation (in-memory + optional persistence)
+ */
+
+import { MemoryBackend, StoreOptions, VectorSearchResult } from './interfaces';
+
+interface StoredEntry {
+  value: unknown;
+  namespace: string;
+  expiresAt?: number;
+  createdAt: number;
+}
+
+interface VectorEntry {
+  embedding: number[];
+  metadata?: unknown;
+}
+
+export class InMemoryBackend implements MemoryBackend {
+  private store: Map<string, StoredEntry> = new Map();
+  private vectors: Map<string, VectorEntry> = new Map();
+  private cleanupInterval?: ReturnType<typeof setInterval>;
+
+  async initialize(): Promise<void> {
+    // Start periodic cleanup of expired entries
+    this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+  }
+
+  async dispose(): Promise<void> {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    this.store.clear();
+    this.vectors.clear();
+  }
+
+  async set<T>(key: string, value: T, options?: StoreOptions): Promise<void> {
+    const entry: StoredEntry = {
+      value,
+      namespace: options?.namespace ?? 'default',
+      createdAt: Date.now(),
+    };
+
+    if (options?.ttl) {
+      entry.expiresAt = Date.now() + options.ttl * 1000;
+    }
+
+    const fullKey = this.buildKey(key, options?.namespace);
+    this.store.set(fullKey, entry);
+  }
+
+  async get<T>(key: string, namespace?: string): Promise<T | undefined> {
+    const fullKey = this.buildKey(key, namespace);
+    const entry = this.store.get(fullKey);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    // Check expiration
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.store.delete(fullKey);
+      return undefined;
+    }
+
+    return entry.value as T;
+  }
+
+  async delete(key: string, namespace?: string): Promise<boolean> {
+    const fullKey = this.buildKey(key, namespace);
+    return this.store.delete(fullKey);
+  }
+
+  async has(key: string, namespace?: string): Promise<boolean> {
+    const value = await this.get(key, namespace);
+    return value !== undefined;
+  }
+
+  async search(pattern: string, limit: number = 100): Promise<string[]> {
+    const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+    const results: string[] = [];
+
+    for (const key of this.store.keys()) {
+      if (regex.test(key)) {
+        results.push(key);
+        if (results.length >= limit) break;
+      }
+    }
+
+    return results;
+  }
+
+  async vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]> {
+    const results: VectorSearchResult[] = [];
+
+    for (const [key, entry] of this.vectors.entries()) {
+      const score = this.cosineSimilarity(embedding, entry.embedding);
+      results.push({ key, score, metadata: entry.metadata });
+    }
+
+    // Sort by score descending and take top k
+    return results
+      .sort((a, b) => b.score - a.score)
+      .slice(0, k);
+  }
+
+  async storeVector(
+    key: string,
+    embedding: number[],
+    metadata?: unknown
+  ): Promise<void> {
+    this.vectors.set(key, { embedding, metadata });
+  }
+
+  private buildKey(key: string, namespace?: string): string {
+    return namespace ? `${namespace}:${key}` : key;
+  }
+
+  private cosineSimilarity(a: number[], b: number[]): number {
+    if (a.length !== b.length) {
+      throw new Error('Vectors must have same dimension');
+    }
+
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  // Utility methods
+
+  getStats(): { entries: number; vectors: number } {
+    return {
+      entries: this.store.size,
+      vectors: this.vectors.size,
+    };
+  }
+
+  async clear(namespace?: string): Promise<void> {
+    if (namespace) {
+      const prefix = `${namespace}:`;
+      for (const key of this.store.keys()) {
+        if (key.startsWith(prefix)) {
+          this.store.delete(key);
+        }
+      }
+    } else {
+      this.store.clear();
+    }
+  }
+}