@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/parallel-executor.js

@@ -0,0 +1,378 @@
+/**
+ * Parallel Executor
+ *
+ * Executes multiple tasks in parallel with different strategies:
+ * Race, Consensus, BestOf, Merge, and Fallback.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/parallel-executor
+ * @version 3.0.0
+ */
+
+const EventEmitter = require("events");
+const { AttemptJournal } = require("./attempt-journal");
+
+// ---------------------------------------------------------------------------
+//  Enums
+// ---------------------------------------------------------------------------
+
+const ExecutionMode = {
+  RACE: "race", // First successful result wins
+  CONSENSUS: "consensus", // Majority must agree
+  BEST_OF: "best-of", // Compare all by quality score
+  MERGE: "merge", // Combine all outputs
+  FALLBACK: "fallback", // Try sequentially until one succeeds
+};
+
+// ---------------------------------------------------------------------------
+//  ParallelExecutor
+// ---------------------------------------------------------------------------
+
+class ParallelExecutor extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {number} [config.concurrencyLimit=4]  Max simultaneous tasks.
+   * @param {number} [config.timeout=300000]      Per-task timeout (5 min).
+   * @param {Function} [config.qualityScorer]     Custom scorer (output) => number.
+   */
+  constructor(config = {}) {
+    super();
+    this.concurrencyLimit = config.concurrencyLimit || 4;
+    this.timeout = config.timeout || 300000;
+    this.qualityScorer = config.qualityScorer || this._defaultScorer;
+    // v3.0.0 — AttemptJournal for FALLBACK diversity enforcement
+    // High similarity threshold (0.95) because FALLBACK tasks are intentionally
+    // different strategies — only block truly identical approaches, not similar names.
+    this.attemptJournal =
+      config.attemptJournal ||
+      new AttemptJournal({ maxAttempts: 3, similarityThreshold: 0.95 });
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Execute an array of task functions using the specified mode.
+   *
+   * Each task is an async function that returns
+   * `{ success: boolean, output: any, [error]: string }`.
+   *
+   * @param {Function[]} tasks - Array of async task functions.
+   * @param {string} mode      - One of ExecutionMode values.
+   * @returns {Promise<Object>} Aggregated result.
+   */
+  async execute(tasks, mode = ExecutionMode.FALLBACK) {
+    if (!tasks || tasks.length === 0) {
+      return { success: false, error: "No tasks provided" };
+    }
+
+    this.emit("execution-start", { mode, taskCount: tasks.length });
+
+    let result;
+    switch (mode) {
+      case ExecutionMode.RACE:
+        result = await this._executeRace(tasks);
+        break;
+      case ExecutionMode.CONSENSUS:
+        result = await this._executeConsensus(tasks);
+        break;
+      case ExecutionMode.BEST_OF:
+        result = await this._executeBestOf(tasks);
+        break;
+      case ExecutionMode.MERGE:
+        result = await this._executeMerge(tasks);
+        break;
+      case ExecutionMode.FALLBACK:
+      default:
+        result = await this._executeFallback(tasks);
+        break;
+    }
+
+    this.emit("execution-end", { mode, success: result.success });
+    return result;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Strategy Implementations
+  // -----------------------------------------------------------------------
+
+  /**
+   * RACE: Return the first successful result.
+   * All tasks run in parallel; first to succeed wins.
+   * @private
+   */
+  async _executeRace(tasks) {
+    const wrapped = tasks.map((fn) => this._wrapTimeout(fn));
+
+    return new Promise((resolve) => {
+      let resolved = false;
+      let pending = wrapped.length;
+
+      const tryResolve = (result) => {
+        if (resolved) return;
+        if (result.success) {
+          resolved = true;
+          resolve({ ...result, mode: ExecutionMode.RACE });
+        } else {
+          pending--;
+          if (pending === 0) {
+            resolve({
+              success: false,
+              error: "All tasks failed",
+              mode: ExecutionMode.RACE,
+            });
+          }
+        }
+      };
+
+      for (const fn of wrapped) {
+        fn()
+          .then(tryResolve)
+          .catch(() => tryResolve({ success: false }));
+      }
+    });
+  }
+
+  /**
+   * CONSENSUS: Run all tasks, return result shared by the majority.
+   * @private
+   */
+  async _executeConsensus(tasks) {
+    const results = await this._runAll(tasks);
+    const successes = results.filter((r) => r.success);
+
+    if (successes.length === 0) {
+      return {
+        success: false,
+        error: "No tasks succeeded",
+        mode: ExecutionMode.CONSENSUS,
+      };
+    }
+
+    // Group by output (stringified for comparison)
+    const groups = new Map();
+    for (const r of successes) {
+      const key = JSON.stringify(r.output);
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(r);
+    }
+
+    // Find the largest group
+    let majorityGroup = [];
+    for (const group of groups.values()) {
+      if (group.length > majorityGroup.length) {
+        majorityGroup = group;
+      }
+    }
+
+    const majority = majorityGroup.length > results.length / 2;
+
+    return {
+      success: true,
+      output: majorityGroup[0].output,
+      consensus: majority,
+      agreementCount: majorityGroup.length,
+      totalCount: results.length,
+      mode: ExecutionMode.CONSENSUS,
+    };
+  }
+
+  /**
+   * BEST_OF: Run all tasks, pick the one with the highest quality score.
+   * @private
+   */
+  async _executeBestOf(tasks) {
+    const results = await this._runAll(tasks);
+    const successes = results.filter((r) => r.success);
+
+    if (successes.length === 0) {
+      return {
+        success: false,
+        error: "No tasks succeeded",
+        mode: ExecutionMode.BEST_OF,
+      };
+    }
+
+    let best = successes[0];
+    let bestScore = this.qualityScorer(best.output);
+
+    for (let i = 1; i < successes.length; i++) {
+      const score = this.qualityScorer(successes[i].output);
+      if (score > bestScore) {
+        best = successes[i];
+        bestScore = score;
+      }
+    }
+
+    return {
+      ...best,
+      qualityScore: bestScore,
+      candidateCount: successes.length,
+      mode: ExecutionMode.BEST_OF,
+    };
+  }
+
+  /**
+   * MERGE: Run all tasks, combine their outputs into one.
+   * @private
+   */
+  async _executeMerge(tasks) {
+    const results = await this._runAll(tasks);
+    const successes = results.filter((r) => r.success);
+
+    if (successes.length === 0) {
+      return {
+        success: false,
+        error: "No tasks succeeded",
+        mode: ExecutionMode.MERGE,
+      };
+    }
+
+    const mergedOutputs = successes.map((r) => r.output);
+
+    return {
+      success: true,
+      output: mergedOutputs,
+      mergedCount: mergedOutputs.length,
+      mode: ExecutionMode.MERGE,
+    };
+  }
+
+  /**
+   * FALLBACK: Try tasks sequentially; return first success.
+   * @private
+   */
+  async _executeFallback(tasks) {
+    // Stable taskId across all iterations within this FALLBACK call
+    const taskId = `fallback-${Date.now()}`;
+
+    for (let i = 0; i < tasks.length; i++) {
+      const approachDesc = `fallback alternative number${i} using strategy${i} variant${i}`;
+
+      // Check approach diversity before attempting
+      const check = this.attemptJournal.checkApproach(taskId, approachDesc);
+      if (!check.allowed) {
+        this.emit("fallback-blocked", {
+          taskIndex: i,
+          reason: check.reason,
+          suggestions: check.suggestions,
+        });
+        continue; // Skip this task — too similar to a previous failure
+      }
+
+      // Check forced escalation
+      if (this.attemptJournal.mustEscalate(taskId)) {
+        this.emit("fallback-escalate", {
+          taskId,
+          journal: this.attemptJournal.getSummary(taskId),
+        });
+        break;
+      }
+
+      try {
+        const result = await this._wrapTimeout(tasks[i])();
+        if (result.success) {
+          this.attemptJournal.clear(taskId);
+          return { ...result, fallbackIndex: i, mode: ExecutionMode.FALLBACK };
+        }
+
+        // Record failure for diversity tracking
+        this.attemptJournal.record(taskId, {
+          approach: approachDesc,
+          error: result.error || "task returned success: false",
+          success: false,
+        });
+      } catch (err) {
+        this.attemptJournal.record(taskId, {
+          approach: approachDesc,
+          error: err.message,
+          success: false,
+        });
+      }
+    }
+
+    return {
+      success: false,
+      error: "All tasks failed",
+      mode: ExecutionMode.FALLBACK,
+      escalated: this.attemptJournal.mustEscalate(taskId),
+      journal: this.attemptJournal.getSummary(taskId),
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  //  Helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Run all tasks in parallel (respecting concurrency limit) via
+   * Promise.allSettled.
+   * @private
+   */
+  async _runAll(tasks) {
+    const chunks = [];
+    for (let i = 0; i < tasks.length; i += this.concurrencyLimit) {
+      chunks.push(tasks.slice(i, i + this.concurrencyLimit));
+    }
+
+    const allResults = [];
+
+    for (const chunk of chunks) {
+      const settled = await Promise.allSettled(
+        chunk.map((fn) => this._wrapTimeout(fn)()),
+      );
+
+      for (const s of settled) {
+        if (s.status === "fulfilled") {
+          allResults.push(s.value);
+        } else {
+          allResults.push({
+            success: false,
+            error: s.reason?.message || "Unknown error",
+          });
+        }
+      }
+    }
+
+    return allResults;
+  }
+
+  /**
+   * Wrap an async function with a timeout.
+   * @param {Function} fn
+   * @returns {Function}
+   */
+  _wrapTimeout(fn) {
+    const timeout = this.timeout;
+    return () =>
+      Promise.race([
+        fn(),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error("Task timeout")), timeout),
+        ),
+      ]);
+  }
+
+  /**
+   * Default quality scorer (simple heuristic on string output).
+   * @param {*} output
+   * @returns {number}
+   */
+  _defaultScorer(output) {
+    if (!output) return 0;
+    const str = typeof output === "string" ? output : JSON.stringify(output);
+    let score = 0;
+    if (str.length > 100) score += 1;
+    if (str.length > 500) score += 1;
+    if (str.includes("```")) score += 2;
+    return score;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { ParallelExecutor, ExecutionMode };

package/.merlin-core/core/execution/parallel-monitor.js

@@ -0,0 +1,201 @@
+/**
+ * Parallel Monitor
+ *
+ * Monitors parallel execution and collects metrics.
+ * Tracks running tasks with start time, status, and progress.
+ * Emits 'task-stalled' if no progress update is received within
+ * a configurable timeout.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/parallel-monitor
+ * @version 3.0.0
+ */
+
+const { EventEmitter } = require("events");
+
+// ---------------------------------------------------------------------------
+//  ParallelMonitor
+// ---------------------------------------------------------------------------
+
+class ParallelMonitor extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {number} [config.stallTimeoutMs=60000] Time with no progress before
+   *   emitting 'task-stalled' (default 60 s).
+   */
+  constructor(config = {}) {
+    super();
+    this.stallTimeoutMs = config.stallTimeoutMs || 60000;
+
+    /** @type {Map<string, Object>} taskId -> tracking entry */
+    this._tasks = new Map();
+
+    /** @type {Map<string, NodeJS.Timeout>} taskId -> stall timer */
+    this._timers = new Map();
+  }
+
+  // -----------------------------------------------------------------------
+  //  Tracking lifecycle
+  // -----------------------------------------------------------------------
+
+  /**
+   * Begin tracking a task.
+   *
+   * @param {string} taskId
+   */
+  startTracking(taskId) {
+    this._tasks.set(taskId, {
+      taskId,
+      startTime: Date.now(),
+      status: "running",
+      progress: 0,
+      lastUpdate: Date.now(),
+      result: null,
+    });
+
+    this._resetStallTimer(taskId);
+    this.emit("task-started", { taskId });
+  }
+
+  /**
+   * Update progress for a tracked task.
+   *
+   * @param {string} taskId
+   * @param {number} progress - 0..100.
+   */
+  updateProgress(taskId, progress) {
+    const entry = this._tasks.get(taskId);
+    if (!entry) return;
+
+    entry.progress = progress;
+    entry.lastUpdate = Date.now();
+    this._resetStallTimer(taskId);
+  }
+
+  /**
+   * Mark a task as complete.
+   *
+   * @param {string} taskId
+   * @param {Object} result - Execution result.
+   */
+  completeTask(taskId, result) {
+    const entry = this._tasks.get(taskId);
+    if (!entry) return;
+
+    entry.status = result.success ? "completed" : "failed";
+    entry.progress = 100;
+    entry.result = result;
+    entry.endTime = Date.now();
+    entry.duration = entry.endTime - entry.startTime;
+
+    this._clearStallTimer(taskId);
+    this.emit("task-completed", { taskId, result });
+  }
+
+  // -----------------------------------------------------------------------
+  //  Queries
+  // -----------------------------------------------------------------------
+
+  /**
+   * @returns {number} Count of currently running tasks.
+   */
+  getActiveCount() {
+    let count = 0;
+    for (const entry of this._tasks.values()) {
+      if (entry.status === "running") count++;
+    }
+    return count;
+  }
+
+  /**
+   * Return aggregated metrics across all tracked tasks.
+   *
+   * @returns {Object}
+   */
+  getMetrics() {
+    let running = 0;
+    let completed = 0;
+    let failed = 0;
+    let totalDuration = 0;
+
+    for (const entry of this._tasks.values()) {
+      if (entry.status === "running") running++;
+      else if (entry.status === "completed") {
+        completed++;
+        totalDuration += entry.duration || 0;
+      } else if (entry.status === "failed") {
+        failed++;
+        totalDuration += entry.duration || 0;
+      }
+    }
+
+    return {
+      running,
+      completed,
+      failed,
+      total: this._tasks.size,
+      averageDuration:
+        completed + failed > 0
+          ? Math.round(totalDuration / (completed + failed))
+          : 0,
+    };
+  }
+
+  /**
+   * Wait until all tracked tasks have completed (or timeout expires).
+   *
+   * @param {number} [timeout=600000] Max wait (10 min).
+   * @returns {Promise<Object>} Metrics snapshot when done.
+   */
+  waitForAll(timeout = 600000) {
+    return new Promise((resolve, reject) => {
+      const deadline = Date.now() + timeout;
+
+      const check = () => {
+        if (this.getActiveCount() === 0) {
+          return resolve(this.getMetrics());
+        }
+        if (Date.now() > deadline) {
+          return reject(new Error("waitForAll timeout"));
+        }
+        setTimeout(check, 500);
+      };
+
+      check();
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  //  Stall Detection
+  // -----------------------------------------------------------------------
+
+  /** @private */
+  _resetStallTimer(taskId) {
+    this._clearStallTimer(taskId);
+
+    const timer = setTimeout(() => {
+      const entry = this._tasks.get(taskId);
+      if (entry && entry.status === "running") {
+        this.emit("task-stalled", { taskId, lastUpdate: entry.lastUpdate });
+      }
+    }, this.stallTimeoutMs);
+
+    this._timers.set(taskId, timer);
+  }
+
+  /** @private */
+  _clearStallTimer(taskId) {
+    const timer = this._timers.get(taskId);
+    if (timer) {
+      clearTimeout(timer);
+      this._timers.delete(taskId);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { ParallelMonitor };