@defai.digital/agent-parallel 13.4.0

package/src/context-manager.ts

@@ -0,0 +1,194 @@
+/**
+ * Context Manager
+ *
+ * Manages shared immutable context for parallel agent execution.
+ * Ensures context is frozen before execution and cannot be modified.
+ *
+ * Invariants:
+ * - INV-APE-003: Shared context immutable during execution
+ * - INV-APE-300: Context snapshot timing (frozen before first task)
+ */
+
+import type { SharedContext } from '@defai.digital/contracts';
+import { ParallelExecutionErrorCodes } from '@defai.digital/contracts';
+import type { ContextManager } from './types.js';
+
+/**
+ * Error thrown when context mutation is attempted
+ */
+export class ContextMutationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ContextMutationError';
+  }
+
+  static readonly code = ParallelExecutionErrorCodes.CONTEXT_MUTATION;
+}
+
+/**
+ * Deep freeze an object and all nested objects
+ * INV-APE-003: Ensures true immutability
+ */
+function deepFreeze<T extends object>(obj: T): T {
+  // Get property names
+  const propNames = Object.getOwnPropertyNames(obj) as (keyof T)[];
+
+  // Freeze nested objects first
+  for (const name of propNames) {
+    const value = obj[name];
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+      deepFreeze(value as object);
+    }
+  }
+
+  // Freeze self
+  return Object.freeze(obj);
+}
+
+/**
+ * Creates a context manager for shared immutable context
+ */
+export function createContextManager(): ContextManager {
+  let context: SharedContext | null = null;
+  let frozen = false;
+
+  return {
+    /**
+     * Create frozen shared context
+     * INV-APE-300: Context snapshot timing
+     */
+    create(data: Record<string, unknown>): SharedContext {
+      // Deep clone to prevent external mutation
+      const clonedData = JSON.parse(JSON.stringify(data)) as Record<string, unknown>;
+
+      // Create context object
+      const newContext: SharedContext = {
+        data: clonedData,
+        createdAt: new Date().toISOString(),
+        version: '1',
+      };
+
+      // Deep freeze the entire context
+      // INV-APE-003: Immutable during execution
+      context = deepFreeze(newContext);
+      frozen = true;
+
+      return context;
+    },
+
+    /**
+     * Get read-only view of context
+     */
+    get(): SharedContext | null {
+      return context;
+    },
+
+    /**
+     * Check if context is frozen/immutable
+     */
+    isFrozen(): boolean {
+      return frozen && context !== null && Object.isFrozen(context);
+    },
+
+    /**
+     * Clear context (for cleanup after execution)
+     */
+    clear(): void {
+      context = null;
+      frozen = false;
+    },
+  };
+}
+
+/**
+ * Creates a proxy that throws on any mutation attempt
+ * Alternative approach for stricter runtime enforcement
+ */
+export function createImmutableContextProxy<T extends Record<string, unknown>>(
+  data: T
+): Readonly<T> {
+  const handler: ProxyHandler<T> = {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      // Recursively wrap nested objects
+      if (value && typeof value === 'object') {
+        return createImmutableContextProxy(value as Record<string, unknown>);
+      }
+      return value;
+    },
+
+    set(_target, prop) {
+      throw new ContextMutationError(
+        `Cannot modify shared context: attempted to set "${String(prop)}". ` +
+          'Shared context is immutable during parallel execution (INV-APE-003).'
+      );
+    },
+
+    deleteProperty(_target, prop) {
+      throw new ContextMutationError(
+        `Cannot modify shared context: attempted to delete "${String(prop)}". ` +
+          'Shared context is immutable during parallel execution (INV-APE-003).'
+      );
+    },
+
+    defineProperty(_target, prop) {
+      throw new ContextMutationError(
+        `Cannot modify shared context: attempted to define "${String(prop)}". ` +
+          'Shared context is immutable during parallel execution (INV-APE-003).'
+      );
+    },
+
+    setPrototypeOf() {
+      throw new ContextMutationError(
+        'Cannot modify shared context prototype. ' +
+          'Shared context is immutable during parallel execution (INV-APE-003).'
+      );
+    },
+  };
+
+  return new Proxy(data, handler) as Readonly<T>;
+}
+
+/**
+ * Validates that context data is JSON-serializable
+ */
+export function validateContextData(
+  data: unknown
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  try {
+    // Check JSON serializability
+    JSON.stringify(data);
+  } catch (e) {
+    errors.push(
+      `Context data is not JSON-serializable: ${e instanceof Error ? e.message : 'Unknown error'}`
+    );
+    return { valid: false, errors };
+  }
+
+  // Check for functions (not serializable)
+  function checkForFunctions(obj: unknown, path: string): void {
+    if (typeof obj === 'function') {
+      errors.push(`Context contains function at ${path}`);
+    } else if (obj && typeof obj === 'object') {
+      if (Array.isArray(obj)) {
+        obj.forEach((item, index) => checkForFunctions(item, `${path}[${index}]`));
+      } else {
+        for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+          checkForFunctions(value, path ? `${path}.${key}` : key);
+        }
+      }
+    }
+  }
+
+  checkForFunctions(data, '');
+
+  // Check for circular references (JSON.stringify would have failed)
+  // Already caught above
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/dag-analyzer.ts

@@ -0,0 +1,285 @@
+/**
+ * DAG Analyzer
+ *
+ * Analyzes task dependencies and builds execution layers using topological sort.
+ * Detects circular dependencies and validates DAG structure.
+ *
+ * Invariants:
+ * - INV-APE-002: Dependencies honored (DAG ordering)
+ * - INV-APE-200: Circular dependencies detected before execution
+ */
+
+import type { AgentParallelTask } from '@defai.digital/contracts';
+import { ParallelExecutionErrorCodes } from '@defai.digital/contracts';
+import type { DAGAnalyzer, DAGAnalysisResult, TaskLayer } from './types.js';
+
+/**
+ * Error thrown when DAG analysis fails
+ */
+export class DAGAnalysisError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly cycleNodes?: string[]
+  ) {
+    super(message);
+    this.name = 'DAGAnalysisError';
+  }
+
+  static circularDependency(nodeIds: string[]): DAGAnalysisError {
+    return new DAGAnalysisError(
+      ParallelExecutionErrorCodes.CIRCULAR_DEPENDENCY,
+      `Circular dependency detected: ${nodeIds.join(' -> ')}`,
+      nodeIds
+    );
+  }
+
+  static invalidDependency(taskId: string, depId: string): DAGAnalysisError {
+    return new DAGAnalysisError(
+      ParallelExecutionErrorCodes.INVALID_PLAN,
+      `Task "${taskId}" depends on non-existent task "${depId}"`
+    );
+  }
+}
+
+/**
+ * Creates a DAG analyzer for parallel task execution
+ * Uses Kahn's algorithm for topological sorting
+ */
+export function createDAGAnalyzer(): DAGAnalyzer {
+  /**
+   * Build execution layers using Kahn's algorithm
+   * INV-APE-002: Ensures dependencies honored
+   * INV-APE-200: Detects cycles via incomplete processing
+   */
+  function buildLayers(tasks: AgentParallelTask[]): DAGAnalysisResult {
+    // Handle empty input
+    if (tasks.length === 0) {
+      return {
+        layers: [],
+        totalLayers: 0,
+        maxParallelism: 0,
+        hasCycles: false,
+      };
+    }
+
+    // Build task lookup map
+    const taskMap = new Map<string, AgentParallelTask>();
+    for (const task of tasks) {
+      taskMap.set(task.taskId, task);
+    }
+
+    // Validate all dependencies exist
+    for (const task of tasks) {
+      for (const depId of task.dependencies) {
+        if (!taskMap.has(depId)) {
+          throw DAGAnalysisError.invalidDependency(task.taskId, depId);
+        }
+      }
+    }
+
+    // Calculate in-degree for each task
+    const inDegree = new Map<string, number>();
+    for (const task of tasks) {
+      inDegree.set(task.taskId, task.dependencies.length);
+    }
+
+    // Build reverse dependency map (who depends on me)
+    const dependents = new Map<string, string[]>();
+    for (const task of tasks) {
+      dependents.set(task.taskId, []);
+    }
+    for (const task of tasks) {
+      for (const depId of task.dependencies) {
+        const depList = dependents.get(depId) ?? [];
+        depList.push(task.taskId);
+        dependents.set(depId, depList);
+      }
+    }
+
+    // Build layers using BFS
+    const layers: TaskLayer[] = [];
+    let processedCount = 0;
+
+    // Start with tasks that have no dependencies
+    let currentLayerTaskIds = Array.from(inDegree.entries())
+      .filter(([_, degree]) => degree === 0)
+      .map(([id]) => id);
+
+    let layerIndex = 0;
+
+    while (currentLayerTaskIds.length > 0) {
+      // Get tasks for current layer, sorted by priority (descending)
+      const layerTasks = currentLayerTaskIds
+        .map((id) => taskMap.get(id)!)
+        .sort((a, b) => (b.priority ?? 50) - (a.priority ?? 50));
+
+      layers.push({
+        index: layerIndex,
+        tasks: layerTasks,
+      });
+
+      processedCount += layerTasks.length;
+
+      // Find next layer
+      const nextLayerTaskIds: string[] = [];
+      for (const taskId of currentLayerTaskIds) {
+        const deps = dependents.get(taskId) ?? [];
+        for (const depId of deps) {
+          const degree = (inDegree.get(depId) ?? 0) - 1;
+          inDegree.set(depId, degree);
+
+          if (degree === 0) {
+            nextLayerTaskIds.push(depId);
+          }
+        }
+      }
+
+      currentLayerTaskIds = nextLayerTaskIds;
+      layerIndex++;
+    }
+
+    // Check for cycles - if we didn't process all tasks, there's a cycle
+    const hasCycles = processedCount !== tasks.length;
+    let cycleNodes: string[] | undefined;
+
+    if (hasCycles) {
+      // Find nodes involved in cycle (those not processed)
+      cycleNodes = tasks
+        .filter((t) => (inDegree.get(t.taskId) ?? 0) > 0)
+        .map((t) => t.taskId);
+    }
+
+    // Calculate max parallelism (largest layer)
+    const maxParallelism = Math.max(0, ...layers.map((l) => l.tasks.length));
+
+    const result: DAGAnalysisResult = {
+      layers,
+      totalLayers: layers.length,
+      maxParallelism,
+      hasCycles,
+    };
+
+    // Only include cycleNodes if there are cycles
+    if (cycleNodes) {
+      result.cycleNodes = cycleNodes;
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate DAG structure
+   */
+  function validate(tasks: AgentParallelTask[]): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    // Check for duplicate task IDs
+    const taskIds = new Set<string>();
+    for (const task of tasks) {
+      if (taskIds.has(task.taskId)) {
+        errors.push(`Duplicate task ID: ${task.taskId}`);
+      }
+      taskIds.add(task.taskId);
+    }
+
+    // Check for self-dependencies
+    for (const task of tasks) {
+      if (task.dependencies.includes(task.taskId)) {
+        errors.push(`Task "${task.taskId}" depends on itself`);
+      }
+    }
+
+    // Check for missing dependencies
+    for (const task of tasks) {
+      for (const depId of task.dependencies) {
+        if (!taskIds.has(depId)) {
+          errors.push(`Task "${task.taskId}" depends on non-existent task "${depId}"`);
+        }
+      }
+    }
+
+    // Check for cycles
+    if (errors.length === 0) {
+      const result = buildLayers(tasks);
+      if (result.hasCycles) {
+        errors.push(`Circular dependency detected involving: ${result.cycleNodes?.join(', ')}`);
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  return {
+    analyze(tasks: AgentParallelTask[]): DAGAnalysisResult {
+      const result = buildLayers(tasks);
+
+      // Throw if cycles detected
+      if (result.hasCycles && result.cycleNodes) {
+        throw DAGAnalysisError.circularDependency(result.cycleNodes);
+      }
+
+      return result;
+    },
+
+    validate,
+  };
+}
+
+/**
+ * Utility: Find tasks in a cycle using DFS
+ */
+export function findCyclePath(tasks: AgentParallelTask[]): string[] | null {
+  const taskMap = new Map<string, AgentParallelTask>();
+  for (const task of tasks) {
+    taskMap.set(task.taskId, task);
+  }
+
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+  const path: string[] = [];
+
+  function dfs(taskId: string): boolean {
+    visited.add(taskId);
+    recursionStack.add(taskId);
+    path.push(taskId);
+
+    const task = taskMap.get(taskId);
+    if (task) {
+      for (const depId of task.dependencies) {
+        if (!visited.has(depId)) {
+          if (dfs(depId)) {
+            return true;
+          }
+        } else if (recursionStack.has(depId)) {
+          // Found cycle
+          path.push(depId);
+          return true;
+        }
+      }
+    }
+
+    recursionStack.delete(taskId);
+    path.pop();
+    return false;
+  }
+
+  for (const task of tasks) {
+    if (!visited.has(task.taskId)) {
+      if (dfs(task.taskId)) {
+        // Trim path to only include cycle
+        const lastNode = path[path.length - 1];
+        if (lastNode) {
+          const cycleStart = path.indexOf(lastNode);
+          return path.slice(cycleStart);
+        }
+        return path;
+      }
+    }
+  }
+
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * @defai.digital/agent-parallel
+ *
+ * Parallel Agent Execution Domain
+ *
+ * Provides orchestration for executing multiple agents in parallel
+ * with DAG-based dependency management, shared immutable context,
+ * and configurable result aggregation.
+ *
+ * @module @defai.digital/agent-parallel
+ */
+
+// Main Orchestrator
+export {
+  createAgentParallelOrchestrator,
+  ParallelExecutionError,
+} from './orchestrator.js';
+
+// DAG Analyzer
+export {
+  createDAGAnalyzer,
+  DAGAnalysisError,
+  findCyclePath,
+} from './dag-analyzer.js';
+
+// Context Manager
+export {
+  createContextManager,
+  createImmutableContextProxy,
+  validateContextData,
+  ContextMutationError,
+} from './context-manager.js';
+
+// Result Aggregator
+export {
+  createResultAggregator,
+  AggregationStrategies,
+  createKeyedAggregator,
+  createTransformAggregator,
+  getAggregationStrategy,
+} from './result-aggregator.js';
+
+// Types and Interfaces
+export type {
+  // Orchestrator types
+  AgentParallelOrchestrator,
+  AgentParallelOrchestratorOptions,
+  // Agent executor port
+  AgentExecutorPort,
+  AgentExecuteRequest,
+  AgentExecuteResult,
+  // DAG types
+  DAGAnalyzer,
+  DAGAnalysisResult,
+  TaskLayer,
+  // Context types
+  ContextManager,
+  // Result aggregator types
+  ResultAggregator,
+  ResultAggregatorOptions,
+  AggregationStrategy,
+  CustomAggregator,
+  // Progress types
+  ParallelProgressEvent,
+  ParallelProgressEventType,
+  ParallelProgressCallback,
+} from './types.js';
+
+// Stub implementation for testing
+export { StubAgentExecutor } from './types.js';