@unrdf/knowledge-engine 5.0.1 → 26.4.2

package/src/hook-executor-batching.mjs

@@ -1,277 +0,0 @@
-/**
- * @file Hook Execution Batching Extension
- * @module knowledge-engine/hook-executor-batching
- *
- * @description
- * Extends hook executor with batching capabilities for 30-50% latency reduction.
- * Analyzes hook dependencies and executes independent hooks in parallel.
- */
-
-import { trace, metrics as otelMetrics, SpanStatusCode } from '@opentelemetry/api';
-
-/**
- * Add batching capabilities to a hook executor instance.
- * @param {Object} executor - Hook executor instance
- * @param {Object} [options] - Batching options
- * @returns {Object} Extended executor with batching
- */
-export function addBatchingCapabilities(executor, options = {}) {
-  const { enableOTEL = true, enableBatching = true } = options;
-
-  // OTEL instrumentation
-  let tracer, meter, batchExecutionCounter, batchDurationHistogram, parallelizationGauge;
-  if (enableOTEL) {
-    tracer = trace.getTracer('hook-executor-batching');
-    meter = otelMetrics.getMeter('hook-executor-batching');
-
-    batchExecutionCounter = meter.createCounter('hook.batch.executions', {
-      description: 'Number of batched hook executions',
-    });
-    batchDurationHistogram = meter.createHistogram('hook.batch.duration', {
-      description: 'Batch execution duration in ms',
-      unit: 'ms',
-    });
-    parallelizationGauge = meter.createUpDownCounter('hook.parallelization.ratio', {
-      description: 'Ratio of parallel to sequential executions',
-    });
-  }
-
-  // Extended metrics
-  const batchMetrics = {
-    batchExecutions: 0,
-    parallelExecutions: 0,
-    sequentialExecutions: 0,
-    totalBatchDuration: 0,
-    averageBatchSize: 0,
-  };
-
-  /**
-   * Analyze hook dependencies to determine execution order.
-   * @param {Array} hooks - Array of hook definitions
-   * @returns {Map} Dependency graph
-   * @private
-   */
-  function _analyzeDependencies(hooks) {
-    const dependencies = new Map();
-
-    for (let i = 0; i < hooks.length; i++) {
-      const hook = hooks[i];
-      const hookName = hook.meta?.name || `hook-${i}`;
-
-      // Check if hook has explicit dependencies
-      const hookDeps = hook.meta?.dependencies || [];
-
-      // Check if hook modifies state (before/after hooks may have dependencies)
-      const modifiesState = !!hook.before || !!hook.after;
-
-      // If no explicit dependencies and doesn't modify state, it's independent
-      if (hookDeps.length === 0 && !modifiesState) {
-        dependencies.set(hookName, []);
-      } else {
-        dependencies.set(hookName, hookDeps);
-      }
-    }
-
-    return dependencies;
-  }
-
-  /**
-   * Create execution batches based on dependency analysis.
-   * Independent hooks are grouped into the same batch for parallel execution.
-   * @param {Array} hooks - Array of hook definitions
-   * @param {Map} dependencyGraph - Hook dependency graph
-   * @returns {Array} Array of batches, each containing independent hooks
-   * @private
-   */
-  function _createExecutionBatches(hooks, dependencyGraph) {
-    const batches = [];
-    const processed = new Set();
-
-    while (processed.size < hooks.length) {
-      const batch = [];
-
-      for (let i = 0; i < hooks.length; i++) {
-        const hook = hooks[i];
-        const hookName = hook.meta?.name || `hook-${i}`;
-
-        if (processed.has(hookName)) continue;
-
-        const deps = dependencyGraph.get(hookName) || [];
-
-        // Check if all dependencies have been processed
-        const allDepsProcessed = deps.every(dep => processed.has(dep));
-
-        if (allDepsProcessed) {
-          batch.push(hook);
-          processed.add(hookName);
-        }
-      }
-
-      if (batch.length === 0) {
-        // Circular dependency or unresolvable - add remaining hooks sequentially
-        for (let i = 0; i < hooks.length; i++) {
-          const hook = hooks[i];
-          const hookName = hook.meta?.name || `hook-${i}`;
-          if (!processed.has(hookName)) {
-            batch.push(hook);
-            processed.add(hookName);
-            break;
-          }
-        }
-      }
-
-      if (batch.length > 0) {
-        batches.push(batch);
-      }
-    }
-
-    return batches;
-  }
-
-  /**
-   * Execute hooks with batching for parallel execution (30-50% latency reduction).
-   * Analyzes hook dependencies and batches independent hooks for parallel execution.
-   * @param {Array} hooks - Array of hook definitions
-   * @param {Object} event - The hook event
-   * @param {Object} [executionOptions] - Execution-specific options
-   * @returns {Promise<Array>} Array of execution results
-   */
-  async function executeBatched(hooks, event, executionOptions = {}) {
-    if (!Array.isArray(hooks)) {
-      throw new TypeError('executeBatched: hooks must be an array');
-    }
-
-    const startTime = Date.now();
-    const span = enableOTEL
-      ? tracer.startSpan('hook.batch.execute', {
-          attributes: {
-            'batch.size': hooks.length,
-            'batch.enableBatching': enableBatching,
-          },
-        })
-      : null;
-
-    try {
-      if (!enableBatching || hooks.length === 1) {
-        // Fall back to sequential execution
-        span?.setAttribute('batch.mode', 'sequential');
-        const results = await executor.executeSequential(hooks, event, executionOptions);
-        batchMetrics.sequentialExecutions += hooks.length;
-        span?.end();
-        return results;
-      }
-
-      // Analyze hook dependencies
-      const dependencyGraph = _analyzeDependencies(hooks);
-
-      // Create execution batches (independent hooks in same batch)
-      const batches = _createExecutionBatches(hooks, dependencyGraph);
-
-      span?.setAttribute('batch.count', batches.length);
-      span?.setAttribute('batch.mode', 'batched');
-
-      const allResults = [];
-
-      // Execute batches sequentially, but hooks within each batch in parallel
-      for (let i = 0; i < batches.length; i++) {
-        const batch = batches[i];
-        const batchSpan = enableOTEL
-          ? tracer.startSpan(`hook.batch.${i}`, {
-              attributes: {
-                'batch.index': i,
-                'batch.hookCount': batch.length,
-                'batch.parallelizable': batch.length > 1,
-              },
-            })
-          : null;
-
-        // Execute all hooks in this batch in parallel
-        const batchPromises = batch.map(hook => executor.execute(hook, event, executionOptions));
-
-        const batchResults = await Promise.all(batchPromises);
-        allResults.push(...batchResults);
-
-        batchSpan?.setAttribute('batch.successCount', batchResults.filter(r => r.success).length);
-        batchSpan?.setAttribute('batch.failureCount', batchResults.filter(r => !r.success).length);
-        batchSpan?.end();
-
-        // Stop on first failure in strict mode
-        if (executionOptions.strictMode && batchResults.some(r => !r.success)) {
-          break;
-        }
-      }
-
-      const duration = Date.now() - startTime;
-      batchMetrics.batchExecutions++;
-      batchMetrics.parallelExecutions += hooks.length;
-      batchMetrics.totalBatchDuration += duration;
-      batchMetrics.averageBatchSize =
-        batchMetrics.parallelExecutions / batchMetrics.batchExecutions;
-
-      // Record batch metrics
-      if (enableOTEL) {
-        batchExecutionCounter.add(1, { 'batch.count': batches.length });
-        batchDurationHistogram.record(duration, { 'batch.size': hooks.length });
-
-        const parallelRatio =
-          batchMetrics.parallelExecutions /
-          (batchMetrics.parallelExecutions + batchMetrics.sequentialExecutions);
-        parallelizationGauge.add(parallelRatio * 100);
-
-        span.setAttribute('batch.duration', duration);
-        span.setAttribute('batch.parallelizationRatio', parallelRatio);
-        span.setStatus({ code: SpanStatusCode.OK });
-      }
-
-      span?.end();
-      return allResults;
-    } catch (error) {
-      if (span) {
-        span.recordException(error);
-        span.setStatus({
-          code: SpanStatusCode.ERROR,
-          message: error.message,
-        });
-        span.end();
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Get batching metrics.
-   * @returns {Object} Batching metrics
-   */
-  function getBatchingMetrics() {
-    const parallelizationRatio =
-      batchMetrics.parallelExecutions /
-      (batchMetrics.parallelExecutions + batchMetrics.sequentialExecutions || 1);
-
-    return {
-      ...batchMetrics,
-      parallelizationRatio,
-      averageBatchDuration:
-        batchMetrics.batchExecutions > 0
-          ? batchMetrics.totalBatchDuration / batchMetrics.batchExecutions
-          : 0,
-    };
-  }
-
-  // Extend executor with batching capabilities
-  return {
-    ...executor,
-    executeBatched,
-    getBatchingMetrics,
-    executeWithDependencies: executeBatched, // Override with batching implementation
-  };
-}
-
-/**
- * Create a hook executor with batching capabilities.
- * @param {Object} executor - Base hook executor
- * @param {Object} [options] - Batching options
- * @returns {Object} Extended executor
- */
-export function createBatchingExecutor(executor, options = {}) {
-  return addBatchingCapabilities(executor, options);
-}