@evomap/evolver 1.28.1

package/src/gep/questionGenerator.js

@@ -0,0 +1,212 @@
+// ---------------------------------------------------------------------------
+// questionGenerator -- analyzes evolution context (signals, session transcripts,
+// recent events) and generates proactive questions for the Hub bounty system.
+//
+// Questions are sent via the A2A fetch payload.questions field. The Hub creates
+// bounties from them, enabling multi-agent collaborative problem solving.
+// ---------------------------------------------------------------------------
+
+const fs = require('fs');
+const path = require('path');
+const { getEvolutionDir } = require('./paths');
+
+const QUESTION_STATE_FILE = path.join(getEvolutionDir(), 'question_generator_state.json');
+const MIN_INTERVAL_MS = 3 * 60 * 60 * 1000; // at most once per 3 hours
+const MAX_QUESTIONS_PER_CYCLE = 2;
+
+function readState() {
+  try {
+    if (fs.existsSync(QUESTION_STATE_FILE)) {
+      return JSON.parse(fs.readFileSync(QUESTION_STATE_FILE, 'utf8'));
+    }
+  } catch (_) {}
+  return { lastAskedAt: null, recentQuestions: [] };
+}
+
+function writeState(state) {
+  try {
+    const dir = path.dirname(QUESTION_STATE_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(QUESTION_STATE_FILE, JSON.stringify(state, null, 2) + '\n');
+  } catch (_) {}
+}
+
+function isDuplicate(question, recentQuestions) {
+  var qLower = question.toLowerCase();
+  for (var i = 0; i < recentQuestions.length; i++) {
+    var prev = String(recentQuestions[i] || '').toLowerCase();
+    if (prev === qLower) return true;
+    // fuzzy: if >70% overlap by word set
+    var qWords = new Set(qLower.split(/\s+/).filter(function(w) { return w.length > 2; }));
+    var pWords = new Set(prev.split(/\s+/).filter(function(w) { return w.length > 2; }));
+    if (qWords.size === 0 || pWords.size === 0) continue;
+    var overlap = 0;
+    qWords.forEach(function(w) { if (pWords.has(w)) overlap++; });
+    if (overlap / Math.max(qWords.size, pWords.size) > 0.7) return true;
+  }
+  return false;
+}
+
+/**
+ * Generate proactive questions based on evolution context.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.signals - current cycle signals
+ * @param {object[]} opts.recentEvents - recent EvolutionEvent objects
+ * @param {string} opts.sessionTranscript - recent session transcript
+ * @param {string} opts.memorySnippet - MEMORY.md content
+ * @returns {Array<{ question: string, amount: number, signals: string[] }>}
+ */
+function generateQuestions(opts) {
+  var o = opts || {};
+  var signals = Array.isArray(o.signals) ? o.signals : [];
+  var recentEvents = Array.isArray(o.recentEvents) ? o.recentEvents : [];
+  var transcript = String(o.sessionTranscript || '');
+  var memory = String(o.memorySnippet || '');
+
+  var state = readState();
+
+  // Rate limit: don't ask too frequently
+  if (state.lastAskedAt) {
+    var elapsed = Date.now() - new Date(state.lastAskedAt).getTime();
+    if (elapsed < MIN_INTERVAL_MS) return [];
+  }
+
+  var candidates = [];
+  var signalSet = new Set(signals);
+
+  // --- Strategy 1: Recurring errors the agent cannot resolve ---
+  if (signalSet.has('recurring_error') || signalSet.has('high_failure_ratio')) {
+    var errSig = signals.find(function(s) { return s.startsWith('recurring_errsig'); });
+    if (errSig) {
+      var errDetail = errSig.replace(/^recurring_errsig\(\d+x\):/, '').trim().slice(0, 120);
+      candidates.push({
+        question: 'Recurring error in evolution cycle that auto-repair cannot resolve: ' + errDetail + ' -- What approaches or patches have worked for similar issues?',
+        amount: 0,
+        signals: ['recurring_error', 'auto_repair_failed'],
+        priority: 3,
+      });
+    }
+  }
+
+  // --- Strategy 2: Capability gaps detected from user conversations ---
+  if (signalSet.has('capability_gap') || signalSet.has('unsupported_input_type')) {
+    var gapContext = '';
+    var lines = transcript.split('\n');
+    for (var i = 0; i < lines.length; i++) {
+      if (/not supported|cannot|unsupported|not implemented/i.test(lines[i])) {
+        gapContext = lines[i].replace(/\s+/g, ' ').trim().slice(0, 150);
+        break;
+      }
+    }
+    if (gapContext) {
+      candidates.push({
+        question: 'Capability gap detected in agent environment: ' + gapContext + ' -- How can this be addressed or what alternative approaches exist?',
+        amount: 0,
+        signals: ['capability_gap'],
+        priority: 2,
+      });
+    }
+  }
+
+  // --- Strategy 3: Stagnation / saturation -- seek new directions ---
+  if (signalSet.has('evolution_saturation') || signalSet.has('force_steady_state')) {
+    var recentGenes = [];
+    var last5 = recentEvents.slice(-5);
+    for (var j = 0; j < last5.length; j++) {
+      var genes = last5[j].genes_used;
+      if (Array.isArray(genes) && genes.length > 0) {
+        recentGenes.push(genes[0]);
+      }
+    }
+    var uniqueGenes = Array.from(new Set(recentGenes));
+    candidates.push({
+      question: 'Agent evolution has reached saturation after exhausting genes: [' + uniqueGenes.join(', ') + ']. What new evolution directions, automation patterns, or capability genes would be most valuable?',
+      amount: 0,
+      signals: ['evolution_saturation', 'innovation_needed'],
+      priority: 1,
+    });
+  }
+
+  // --- Strategy 4: Consecutive failure streak -- seek external help ---
+  var failStreak = signals.find(function(s) { return s.startsWith('consecutive_failure_streak_'); });
+  if (failStreak) {
+    var streakCount = parseInt(failStreak.replace('consecutive_failure_streak_', ''), 10) || 0;
+    if (streakCount >= 4) {
+      var failGene = signals.find(function(s) { return s.startsWith('ban_gene:'); });
+      var failGeneId = failGene ? failGene.replace('ban_gene:', '') : 'unknown';
+      candidates.push({
+        question: 'Agent has failed ' + streakCount + ' consecutive evolution cycles (last gene: ' + failGeneId + '). The current approach is exhausted. What alternative strategies or environmental fixes should be tried?',
+        amount: 0,
+        signals: ['failure_streak', 'external_help_needed'],
+        priority: 3,
+      });
+    }
+  }
+
+  // --- Strategy 5: User feature requests the agent can amplify ---
+  if (signalSet.has('user_feature_request') || signals.some(function (s) { return String(s).startsWith('user_feature_request:'); })) {
+    var featureLines = transcript.split('\n').filter(function(l) {
+      return /\b(add|implement|create|build|i want|i need|please add)\b/i.test(l);
+    });
+    if (featureLines.length > 0) {
+      var featureContext = featureLines[0].replace(/\s+/g, ' ').trim().slice(0, 150);
+      candidates.push({
+        question: 'User requested a feature that may benefit from community solutions: ' + featureContext + ' -- Are there existing implementations or best practices for this?',
+        amount: 0,
+        signals: ['user_feature_request', 'community_solution_sought'],
+        priority: 1,
+      });
+    }
+  }
+
+  // --- Strategy 6: Performance bottleneck -- seek optimization patterns ---
+  if (signalSet.has('perf_bottleneck')) {
+    var perfLines = transcript.split('\n').filter(function(l) {
+      return /\b(slow|timeout|latency|bottleneck|high cpu|high memory)\b/i.test(l);
+    });
+    if (perfLines.length > 0) {
+      var perfContext = perfLines[0].replace(/\s+/g, ' ').trim().slice(0, 150);
+      candidates.push({
+        question: 'Performance bottleneck detected: ' + perfContext + ' -- What optimization strategies or architectural patterns address this?',
+        amount: 0,
+        signals: ['perf_bottleneck', 'optimization_sought'],
+        priority: 2,
+      });
+    }
+  }
+
+  if (candidates.length === 0) return [];
+
+  // Sort by priority (higher = more urgent)
+  candidates.sort(function(a, b) { return b.priority - a.priority; });
+
+  // De-duplicate against recently asked questions
+  var recentQTexts = Array.isArray(state.recentQuestions) ? state.recentQuestions : [];
+  var filtered = [];
+  for (var fi = 0; fi < candidates.length && filtered.length < MAX_QUESTIONS_PER_CYCLE; fi++) {
+    if (!isDuplicate(candidates[fi].question, recentQTexts)) {
+      filtered.push(candidates[fi]);
+    }
+  }
+
+  if (filtered.length === 0) return [];
+
+  // Update state
+  var newRecentQuestions = recentQTexts.concat(filtered.map(function(q) { return q.question; }));
+  // Keep only last 20 questions in history
+  if (newRecentQuestions.length > 20) {
+    newRecentQuestions = newRecentQuestions.slice(-20);
+  }
+  writeState({
+    lastAskedAt: new Date().toISOString(),
+    recentQuestions: newRecentQuestions,
+  });
+
+  // Strip internal priority field before returning
+  return filtered.map(function(q) {
+    return { question: q.question, amount: q.amount, signals: q.signals };
+  });
+}
+
+module.exports = { generateQuestions };

package/src/gep/reflection.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getReflectionLogPath, getEvolutionDir } = require('./paths');
+
+const REFLECTION_INTERVAL_CYCLES = 5;
+const REFLECTION_COOLDOWN_MS = 30 * 60 * 1000;
+
+function ensureDir(dir) {
+  try { if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); } catch (_) {}
+}
+
+function shouldReflect({ cycleCount, recentEvents }) {
+  if (!Number.isFinite(cycleCount) || cycleCount < REFLECTION_INTERVAL_CYCLES) return false;
+  if (cycleCount % REFLECTION_INTERVAL_CYCLES !== 0) return false;
+
+  const logPath = getReflectionLogPath();
+  try {
+    if (fs.existsSync(logPath)) {
+      const stat = fs.statSync(logPath);
+      if (Date.now() - stat.mtimeMs < REFLECTION_COOLDOWN_MS) return false;
+    }
+  } catch (_) {}
+
+  return true;
+}
+
+function buildReflectionContext({ recentEvents, signals, memoryAdvice, narrative }) {
+  const parts = ['You are performing a strategic reflection on recent evolution cycles.'];
+  parts.push('Analyze the patterns below and provide concise strategic guidance.');
+  parts.push('');
+
+  if (Array.isArray(recentEvents) && recentEvents.length > 0) {
+    const last10 = recentEvents.slice(-10);
+    const successCount = last10.filter(e => e && e.outcome && e.outcome.status === 'success').length;
+    const failCount = last10.filter(e => e && e.outcome && e.outcome.status === 'failed').length;
+    const intents = {};
+    last10.forEach(e => {
+      const i = e && e.intent ? e.intent : 'unknown';
+      intents[i] = (intents[i] || 0) + 1;
+    });
+    const genes = {};
+    last10.forEach(e => {
+      const g = e && Array.isArray(e.genes_used) && e.genes_used[0] ? e.genes_used[0] : 'unknown';
+      genes[g] = (genes[g] || 0) + 1;
+    });
+
+    parts.push('## Recent Cycle Statistics (last 10)');
+    parts.push(`- Success: ${successCount}, Failed: ${failCount}`);
+    parts.push(`- Intent distribution: ${JSON.stringify(intents)}`);
+    parts.push(`- Gene usage: ${JSON.stringify(genes)}`);
+    parts.push('');
+  }
+
+  if (Array.isArray(signals) && signals.length > 0) {
+    parts.push('## Current Signals');
+    parts.push(signals.slice(0, 20).join(', '));
+    parts.push('');
+  }
+
+  if (memoryAdvice) {
+    parts.push('## Memory Graph Advice');
+    if (memoryAdvice.preferredGeneId) {
+      parts.push(`- Preferred gene: ${memoryAdvice.preferredGeneId}`);
+    }
+    if (Array.isArray(memoryAdvice.bannedGeneIds) && memoryAdvice.bannedGeneIds.length > 0) {
+      parts.push(`- Banned genes: ${memoryAdvice.bannedGeneIds.join(', ')}`);
+    }
+    if (memoryAdvice.explanation) {
+      parts.push(`- Explanation: ${memoryAdvice.explanation}`);
+    }
+    parts.push('');
+  }
+
+  if (narrative) {
+    parts.push('## Recent Evolution Narrative');
+    parts.push(String(narrative).slice(0, 3000));
+    parts.push('');
+  }
+
+  parts.push('## Questions to Answer');
+  parts.push('1. Are there persistent signals being ignored?');
+  parts.push('2. Is the gene selection strategy optimal, or are we stuck in a local maximum?');
+  parts.push('3. Should the balance between repair/optimize/innovate shift?');
+  parts.push('4. Are there capability gaps that no current gene addresses?');
+  parts.push('5. What single strategic adjustment would have the highest impact?');
+  parts.push('');
+  parts.push('Respond with a JSON object: { "insights": [...], "strategy_adjustment": "...", "priority_signals": [...] }');
+
+  return parts.join('\n');
+}
+
+function recordReflection(reflection) {
+  const logPath = getReflectionLogPath();
+  ensureDir(path.dirname(logPath));
+
+  const entry = JSON.stringify({
+    ts: new Date().toISOString(),
+    type: 'reflection',
+    ...reflection,
+  }) + '\n';
+
+  fs.appendFileSync(logPath, entry, 'utf8');
+}
+
+function loadRecentReflections(count) {
+  const n = Number.isFinite(count) ? count : 3;
+  const logPath = getReflectionLogPath();
+  try {
+    if (!fs.existsSync(logPath)) return [];
+    const lines = fs.readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.slice(-n).map(line => {
+      try { return JSON.parse(line); } catch (_) { return null; }
+    }).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = {
+  shouldReflect,
+  buildReflectionContext,
+  recordReflection,
+  loadRecentReflections,
+  REFLECTION_INTERVAL_CYCLES,
+};

package/src/gep/sanitize.js

@@ -0,0 +1,67 @@
+// Pre-publish payload sanitization.
+// Removes sensitive tokens, local paths, emails, and env references
+// from capsule payloads before broadcasting to the hub.
+
+// Patterns to redact (replaced with placeholder)
+const REDACT_PATTERNS = [
+  // API keys & tokens (generic)
+  /Bearer\s+[A-Za-z0-9\-._~+\/]+=*/g,
+  /sk-[A-Za-z0-9]{20,}/g,
+  /token[=:]\s*["']?[A-Za-z0-9\-._~+\/]{16,}["']?/gi,
+  /api[_-]?key[=:]\s*["']?[A-Za-z0-9\-._~+\/]{16,}["']?/gi,
+  /secret[=:]\s*["']?[A-Za-z0-9\-._~+\/]{16,}["']?/gi,
+  /password[=:]\s*["']?[^\s"',;)}\]]{6,}["']?/gi,
+  // GitHub tokens (ghp_, gho_, ghu_, ghs_, github_pat_)
+  /ghp_[A-Za-z0-9]{36,}/g,
+  /gho_[A-Za-z0-9]{36,}/g,
+  /ghu_[A-Za-z0-9]{36,}/g,
+  /ghs_[A-Za-z0-9]{36,}/g,
+  /github_pat_[A-Za-z0-9_]{22,}/g,
+  // AWS access keys
+  /AKIA[0-9A-Z]{16}/g,
+  // OpenAI / Anthropic tokens
+  /sk-proj-[A-Za-z0-9\-_]{20,}/g,
+  /sk-ant-[A-Za-z0-9\-_]{20,}/g,
+  // npm tokens
+  /npm_[A-Za-z0-9]{36,}/g,
+  // Private keys
+  /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----/g,
+  // Basic auth in URLs (redact only credentials, keep :// and @)
+  /(?<=:\/\/)[^@\s]+:[^@\s]+(?=@)/g,
+  // Local filesystem paths
+  /\/home\/[^\s"',;)}\]]+/g,
+  /\/Users\/[^\s"',;)}\]]+/g,
+  /[A-Z]:\\[^\s"',;)}\]]+/g,
+  // Email addresses
+  /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+  // .env file references
+  /\.env(?:\.[a-zA-Z]+)?/g,
+];
+
+const REDACTED = '[REDACTED]';
+
+function redactString(str) {
+  if (typeof str !== 'string') return str;
+  let result = str;
+  for (const pattern of REDACT_PATTERNS) {
+    // Reset lastIndex for global regexes
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, REDACTED);
+  }
+  return result;
+}
+
+/**
+ * Deep-clone and sanitize a capsule payload.
+ * Returns a new object with sensitive values redacted.
+ * Does NOT modify the original.
+ */
+function sanitizePayload(capsule) {
+  if (!capsule || typeof capsule !== 'object') return capsule;
+  return JSON.parse(JSON.stringify(capsule), (_key, value) => {
+    if (typeof value === 'string') return redactString(value);
+    return value;
+  });
+}
+
+module.exports = { sanitizePayload, redactString };

package/src/gep/selector.js

@@ -0,0 +1,250 @@
+function matchPatternToSignals(pattern, signals) {
+  if (!pattern || !signals || signals.length === 0) return false;
+  const p = String(pattern);
+  const sig = signals.map(s => String(s));
+
+  // Regex pattern: /body/flags
+  const regexLike = p.length >= 2 && p.startsWith('/') && p.lastIndexOf('/') > 0;
+  if (regexLike) {
+    const lastSlash = p.lastIndexOf('/');
+    const body = p.slice(1, lastSlash);
+    const flags = p.slice(lastSlash + 1);
+    try {
+      const re = new RegExp(body, flags || 'i');
+      return sig.some(s => re.test(s));
+    } catch (e) {
+      // fallback to substring
+    }
+  }
+
+  // Multi-language alias: "en_term|zh_term|ja_term" -- any branch matching = hit
+  if (p.includes('|') && !p.startsWith('/')) {
+    const branches = p.split('|').map(b => b.trim().toLowerCase()).filter(Boolean);
+    return branches.some(needle => sig.some(s => s.toLowerCase().includes(needle)));
+  }
+
+  const needle = p.toLowerCase();
+  return sig.some(s => s.toLowerCase().includes(needle));
+}
+
+function scoreGene(gene, signals) {
+  if (!gene || gene.type !== 'Gene') return 0;
+  const patterns = Array.isArray(gene.signals_match) ? gene.signals_match : [];
+  if (patterns.length === 0) return 0;
+  let score = 0;
+  for (const pat of patterns) {
+    if (matchPatternToSignals(pat, signals)) score += 1;
+  }
+  return score;
+}
+
+// Population-size-dependent drift intensity.
+// In population genetics, genetic drift is stronger in small populations (Ne).
+// driftIntensity: 0 = pure selection, 1 = pure drift (random).
+// Formula: intensity = 1 / sqrt(Ne) where Ne = effective population size.
+// This replaces the binary driftEnabled flag with a continuous spectrum.
+function computeDriftIntensity(opts) {
+  // If explicitly enabled/disabled, use that as the baseline
+  var driftEnabled = !!(opts && opts.driftEnabled);
+
+  // Effective population size: active gene count in the pool
+  var effectivePopulationSize = opts && Number.isFinite(Number(opts.effectivePopulationSize))
+    ? Number(opts.effectivePopulationSize)
+    : null;
+
+  // If no Ne provided, fall back to gene pool size
+  var genePoolSize = opts && Number.isFinite(Number(opts.genePoolSize))
+    ? Number(opts.genePoolSize)
+    : null;
+
+  var ne = effectivePopulationSize || genePoolSize || null;
+
+  if (driftEnabled) {
+    // Explicit drift: use moderate-to-high intensity
+    return ne && ne > 1 ? Math.min(1, 1 / Math.sqrt(ne) + 0.3) : 0.7;
+  }
+
+  if (ne != null && ne > 0) {
+    // Population-dependent drift: small population = more drift
+    // Ne=1: intensity=1.0 (pure drift), Ne=25: intensity=0.2, Ne=100: intensity=0.1
+    return Math.min(1, 1 / Math.sqrt(ne));
+  }
+
+  return 0; // No drift info available, pure selection
+}
+
+function selectGene(genes, signals, opts) {
+  const genesList = Array.isArray(genes) ? genes : [];
+  const bannedGeneIds = opts && opts.bannedGeneIds ? opts.bannedGeneIds : new Set();
+  const driftEnabled = !!(opts && opts.driftEnabled);
+  const preferredGeneId = opts && typeof opts.preferredGeneId === 'string' ? opts.preferredGeneId : null;
+
+  // Compute continuous drift intensity based on effective population size
+  var driftIntensity = computeDriftIntensity({
+    driftEnabled: driftEnabled,
+    effectivePopulationSize: opts && opts.effectivePopulationSize,
+    genePoolSize: genesList.length,
+  });
+  var useDrift = driftEnabled || driftIntensity > 0.15;
+
+  var DISTILLED_PREFIX = 'gene_distilled_';
+  var DISTILLED_SCORE_FACTOR = 0.8;
+
+  const scored = genesList
+    .map(g => {
+      var s = scoreGene(g, signals);
+      if (s > 0 && g.id && String(g.id).startsWith(DISTILLED_PREFIX)) s *= DISTILLED_SCORE_FACTOR;
+      return { gene: g, score: s };
+    })
+    .filter(x => x.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (scored.length === 0) return { selected: null, alternatives: [], driftIntensity: driftIntensity };
+
+  // Memory graph preference: only override when the preferred gene is already a match candidate.
+  if (preferredGeneId) {
+    const preferred = scored.find(x => x.gene && x.gene.id === preferredGeneId);
+    if (preferred && (useDrift || !bannedGeneIds.has(preferredGeneId))) {
+      const rest = scored.filter(x => x.gene && x.gene.id !== preferredGeneId);
+      const filteredRest = useDrift ? rest : rest.filter(x => x.gene && !bannedGeneIds.has(x.gene.id));
+      return {
+        selected: preferred.gene,
+        alternatives: filteredRest.slice(0, 4).map(x => x.gene),
+        driftIntensity: driftIntensity,
+      };
+    }
+  }
+
+  // Low-efficiency suppression: do not repeat low-confidence paths unless drift is active.
+  const filtered = useDrift ? scored : scored.filter(x => x.gene && !bannedGeneIds.has(x.gene.id));
+  if (filtered.length === 0) return { selected: null, alternatives: scored.slice(0, 4).map(x => x.gene), driftIntensity: driftIntensity };
+
+  // Stochastic selection under drift: with probability proportional to driftIntensity,
+  // pick a random gene from the top candidates instead of always picking the best.
+  var selectedIdx = 0;
+  if (driftIntensity > 0 && filtered.length > 1 && Math.random() < driftIntensity) {
+    // Weighted random selection from top candidates (favor higher-scoring but allow lower)
+    var topN = Math.min(filtered.length, Math.max(2, Math.ceil(filtered.length * driftIntensity)));
+    selectedIdx = Math.floor(Math.random() * topN);
+  }
+
+  return {
+    selected: filtered[selectedIdx].gene,
+    alternatives: filtered.filter(function(_, i) { return i !== selectedIdx; }).slice(0, 4).map(x => x.gene),
+    driftIntensity: driftIntensity,
+  };
+}
+
+function selectCapsule(capsules, signals) {
+  const scored = (capsules || [])
+    .map(c => {
+      const triggers = Array.isArray(c.trigger) ? c.trigger : [];
+      const score = triggers.reduce((acc, t) => (matchPatternToSignals(t, signals) ? acc + 1 : acc), 0);
+      return { capsule: c, score };
+    })
+    .filter(x => x.score > 0)
+    .sort((a, b) => b.score - a.score);
+  return scored.length ? scored[0].capsule : null;
+}
+
+function computeSignalOverlap(signalsA, signalsB) {
+  if (!Array.isArray(signalsA) || !Array.isArray(signalsB)) return 0;
+  if (signalsA.length === 0 || signalsB.length === 0) return 0;
+  var setB = new Set(signalsB.map(function (s) { return String(s).toLowerCase(); }));
+  var hits = 0;
+  for (var i = 0; i < signalsA.length; i++) {
+    if (setB.has(String(signalsA[i]).toLowerCase())) hits++;
+  }
+  return hits / Math.max(signalsA.length, 1);
+}
+
+var FAILED_CAPSULE_BAN_THRESHOLD = 2;
+var FAILED_CAPSULE_OVERLAP_MIN = 0.6;
+
+function banGenesFromFailedCapsules(failedCapsules, signals, existingBans) {
+  var bans = existingBans instanceof Set ? new Set(existingBans) : new Set();
+  if (!Array.isArray(failedCapsules) || failedCapsules.length === 0) return bans;
+  var geneFailCounts = {};
+  for (var i = 0; i < failedCapsules.length; i++) {
+    var fc = failedCapsules[i];
+    if (!fc || !fc.gene) continue;
+    var overlap = computeSignalOverlap(signals, fc.trigger || []);
+    if (overlap < FAILED_CAPSULE_OVERLAP_MIN) continue;
+    var gid = String(fc.gene);
+    geneFailCounts[gid] = (geneFailCounts[gid] || 0) + 1;
+  }
+  var keys = Object.keys(geneFailCounts);
+  for (var j = 0; j < keys.length; j++) {
+    if (geneFailCounts[keys[j]] >= FAILED_CAPSULE_BAN_THRESHOLD) {
+      bans.add(keys[j]);
+    }
+  }
+  return bans;
+}
+
+function selectGeneAndCapsule({ genes, capsules, signals, memoryAdvice, driftEnabled, failedCapsules }) {
+  const bannedGeneIds =
+    memoryAdvice && memoryAdvice.bannedGeneIds instanceof Set ? memoryAdvice.bannedGeneIds : new Set();
+  const preferredGeneId = memoryAdvice && memoryAdvice.preferredGeneId ? memoryAdvice.preferredGeneId : null;
+
+  var effectiveBans = banGenesFromFailedCapsules(
+    Array.isArray(failedCapsules) ? failedCapsules : [],
+    signals,
+    bannedGeneIds
+  );
+
+  const { selected, alternatives, driftIntensity } = selectGene(genes, signals, {
+    bannedGeneIds: effectiveBans,
+    preferredGeneId,
+    driftEnabled: !!driftEnabled,
+  });
+  const capsule = selectCapsule(capsules, signals);
+  const selector = buildSelectorDecision({
+    gene: selected,
+    capsule,
+    signals,
+    alternatives,
+    memoryAdvice,
+    driftEnabled,
+    driftIntensity,
+  });
+  return {
+    selectedGene: selected,
+    capsuleCandidates: capsule ? [capsule] : [],
+    selector,
+    driftIntensity,
+  };
+}
+
+function buildSelectorDecision({ gene, capsule, signals, alternatives, memoryAdvice, driftEnabled, driftIntensity }) {
+  const reason = [];
+  if (gene) reason.push('signals match gene.signals_match');
+  if (capsule) reason.push('capsule trigger matches signals');
+  if (!gene) reason.push('no matching gene found; new gene may be required');
+  if (signals && signals.length) reason.push(`signals: ${signals.join(', ')}`);
+
+  if (memoryAdvice && Array.isArray(memoryAdvice.explanation) && memoryAdvice.explanation.length) {
+    reason.push(`memory_graph: ${memoryAdvice.explanation.join(' | ')}`);
+  }
+  if (driftEnabled) {
+    reason.push('random_drift_override: true');
+  }
+  if (Number.isFinite(driftIntensity) && driftIntensity > 0) {
+    reason.push(`drift_intensity: ${driftIntensity.toFixed(3)}`);
+  }
+
+  return {
+    selected: gene ? gene.id : null,
+    reason,
+    alternatives: Array.isArray(alternatives) ? alternatives.map(g => g.id) : [],
+  };
+}
+
+module.exports = {
+  selectGeneAndCapsule,
+  selectGene,
+  selectCapsule,
+  buildSelectorDecision,
+  matchPatternToSignals,
+};
+