@saulwade/swl-ses 1.1.3 → 1.2.0

package/scripts/lib/eval-self-correct.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * eval-self-correct.js — Loop de auto-corrección para outputs invalidos.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/self-correct.ts`.
+ * Adaptado a swl-ses: en lugar de un MemoryProvider que llama a un LLM, este
+ * módulo expone un loop genérico que:
+ *
+ *   1. Ejecuta una función productora.
+ *   2. Valida el output con un validador.
+ *   3. Si falla, re-ejecuta con el prompt ampliado con un sufijo más estricto.
+ *   4. Repite hasta `maxRetries` o éxito.
+ *
+ * El productor es agnóstico: puede ser una llamada a Claude (Skill o Bash),
+ * o cualquier función async que produzca un output basado en un prompt.
+ *
+ * No intenta automatizar llamadas LLM — el caller pasa la función concreta.
+ * Esto mantiene swl-ses zero-deps.
+ *
+ * @module scripts/lib/eval-self-correct
+ */
+
+const SUFIJO_ESTRICTO = `
+
+IMPORTANTE: Tu respuesta anterior fue inválida. Por favor asegúrate de que tu
+output siga ESTRICTAMENTE el formato requerido. Cada campo obligatorio debe
+estar presente con valores válidos.
+
+Errores detectados en el intento anterior:
+{{ERRORS}}
+`;
+
+/**
+ * Ejecuta un loop de auto-corrección sobre una función productora.
+ *
+ * @param {object} opts
+ * @param {function(string, string): Promise<string>} opts.productor - Recibe (sysPrompt, userPrompt) y devuelve output.
+ * @param {function(string): {valid: boolean, errors?: string[]}} opts.validador
+ * @param {string} opts.sysPrompt
+ * @param {string} opts.userPrompt
+ * @param {number} [opts.maxRetries=1] - Número máximo de reintentos tras fallo inicial.
+ * @returns {Promise<{ output: string, valid: boolean, retried: boolean, intentos: number, errors?: string[] }>}
+ */
+async function compresseConReintento(opts) {
+  const { productor, validador, sysPrompt, userPrompt, maxRetries = 1 } = opts;
+
+  if (typeof productor !== 'function') {
+    throw new Error('productor debe ser una función async (sysPrompt, userPrompt) => Promise<string>');
+  }
+  if (typeof validador !== 'function') {
+    throw new Error('validador debe ser una función (output) => {valid, errors?}');
+  }
+
+  // Intento 1
+  const primerOutput = await productor(sysPrompt, userPrompt);
+  const primerResultado = validador(primerOutput);
+  if (primerResultado.valid) {
+    return {
+      output: primerOutput,
+      valid: true,
+      retried: false,
+      intentos: 1,
+    };
+  }
+
+  let ultimoOutput = primerOutput;
+  let ultimosErrores = primerResultado.errors || [];
+
+  for (let i = 0; i < maxRetries; i++) {
+    const erroresFmt = ultimosErrores.length > 0
+      ? ultimosErrores.map(e => `  - ${e}`).join('\n')
+      : '  (sin detalle)';
+    const sysAmpliado = sysPrompt + SUFIJO_ESTRICTO.replace('{{ERRORS}}', erroresFmt);
+
+    const reintentoOutput = await productor(sysAmpliado, userPrompt);
+    const reintentoResultado = validador(reintentoOutput);
+
+    if (reintentoResultado.valid) {
+      return {
+        output: reintentoOutput,
+        valid: true,
+        retried: true,
+        intentos: i + 2,
+      };
+    }
+
+    ultimoOutput = reintentoOutput;
+    ultimosErrores = reintentoResultado.errors || [];
+  }
+
+  return {
+    output: ultimoOutput,
+    valid: false,
+    retried: maxRetries > 0,
+    intentos: maxRetries + 1,
+    errors: ultimosErrores,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  compresseConReintento,
+  SUFIJO_ESTRICTO,
+};

package/scripts/lib/eval-validator.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * eval-validator.js — Validador JSON Schema-lite para outputs SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/validator.ts`. Adaptado a
+ * swl-ses: sin Zod (mantiene principio zero-deps). Implementación propia que
+ * cubre el subset de JSON Schema usado por `eval-schemas.js`:
+ *   - type: object | array | string | number | integer | boolean
+ *   - required, properties (object)
+ *   - items, minItems (array)
+ *   - minLength, maxLength (string)
+ *   - minimum, maximum (number)
+ *   - enum
+ *
+ * Funciones puras zero-deps. Backward compatible: schemas pueden agregar
+ * keywords nuevos en el futuro sin romper validaciones existentes.
+ *
+ * @module scripts/lib/eval-validator
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function obtenerTipo(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function esEntero(value) {
+  return typeof value === 'number' && Number.isInteger(value);
+}
+
+// ── validadores por tipo ──────────────────────────────────────────────────────
+
+function validarString(value, schema, errors, ruta) {
+  if (typeof value !== 'string') {
+    errors.push(`${ruta}: esperado string, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+    errors.push(`${ruta}: longitud ${value.length} < minLength ${schema.minLength}`);
+  }
+  if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+    errors.push(`${ruta}: longitud ${value.length} > maxLength ${schema.maxLength}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${ruta}: valor "${value}" no en enum [${schema.enum.join(', ')}]`);
+  }
+}
+
+function validarNumber(value, schema, errors, ruta) {
+  if (schema.type === 'integer') {
+    if (!esEntero(value)) {
+      errors.push(`${ruta}: esperado integer, recibido ${obtenerTipo(value)}`);
+      return;
+    }
+  } else if (typeof value !== 'number') {
+    errors.push(`${ruta}: esperado number, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (typeof schema.minimum === 'number' && value < schema.minimum) {
+    errors.push(`${ruta}: valor ${value} < minimum ${schema.minimum}`);
+  }
+  if (typeof schema.maximum === 'number' && value > schema.maximum) {
+    errors.push(`${ruta}: valor ${value} > maximum ${schema.maximum}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${ruta}: valor ${value} no en enum`);
+  }
+}
+
+function validarBoolean(value, schema, errors, ruta) {
+  if (typeof value !== 'boolean') {
+    errors.push(`${ruta}: esperado boolean, recibido ${obtenerTipo(value)}`);
+  }
+}
+
+function validarArray(value, schema, errors, ruta) {
+  if (!Array.isArray(value)) {
+    errors.push(`${ruta}: esperado array, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+    errors.push(`${ruta}: ${value.length} items < minItems ${schema.minItems}`);
+  }
+  if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+    errors.push(`${ruta}: ${value.length} items > maxItems ${schema.maxItems}`);
+  }
+  if (schema.items) {
+    for (let i = 0; i < value.length; i++) {
+      validarValor(value[i], schema.items, errors, `${ruta}[${i}]`);
+    }
+  }
+}
+
+function validarObject(value, schema, errors, ruta) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`${ruta}: esperado object, recibido ${obtenerTipo(value)}`);
+    return;
+  }
+  if (Array.isArray(schema.required)) {
+    for (const key of schema.required) {
+      if (!(key in value)) {
+        errors.push(`${ruta}: campo requerido faltante: "${key}"`);
+      }
+    }
+  }
+  if (schema.properties && typeof schema.properties === 'object') {
+    for (const [key, subSchema] of Object.entries(schema.properties)) {
+      if (key in value) {
+        validarValor(value[key], subSchema, errors, `${ruta}.${key}`);
+      }
+    }
+  }
+}
+
+function validarValor(value, schema, errors, ruta) {
+  if (!schema || typeof schema !== 'object') return;
+
+  switch (schema.type) {
+    case 'string':  validarString(value, schema, errors, ruta); break;
+    case 'number':
+    case 'integer': validarNumber(value, schema, errors, ruta); break;
+    case 'boolean': validarBoolean(value, schema, errors, ruta); break;
+    case 'array':   validarArray(value, schema, errors, ruta); break;
+    case 'object':  validarObject(value, schema, errors, ruta); break;
+    default:
+      // Sin type explícito: validar enum si aplica, sino aceptar
+      if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        errors.push(`${ruta}: valor no en enum`);
+      }
+  }
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Valida un valor contra un schema JSON-lite.
+ * @param {*} value
+ * @param {object} schema
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validar(value, schema) {
+  const errors = [];
+  validarValor(value, schema, errors, '$');
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Valida input contra schema, devolviendo formato compatible con eval results.
+ * @param {object} schema
+ * @param {*} data
+ * @param {string} functionId
+ * @returns {object} { valid, data?, result? }
+ */
+function validarInput(schema, data, functionId) {
+  const result = validar(data, schema);
+  if (result.valid) {
+    return { valid: true, data };
+  }
+  return {
+    valid: false,
+    result: {
+      valid: false,
+      errors: result.errors,
+      qualityScore: 0,
+      latencyMs: 0,
+      functionId: functionId || 'unknown',
+    },
+  };
+}
+
+/**
+ * Conveniencia: valida output (alias de validarInput).
+ */
+const validarOutput = validarInput;
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  validar,
+  validarInput,
+  validarOutput,
+};

package/scripts/lib/jaccard-similarity.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * jaccard-similarity.js — Métrica de Jaccard sobre conjuntos de tokens.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/functions/auto-forget.ts`
+ * para detectar memorias contradictorias/duplicadas con vocabulario compartido.
+ *
+ * Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * Propiedades:
+ *   - Rango [0, 1]: 0 = sin overlap, 1 = idénticos.
+ *   - Simétrico: J(A, B) = J(B, A).
+ *   - Independiente de longitudes absolutas (ambos cortos pueden ser 1.0).
+ *
+ * Sin dependencias — Node stdlib only. Funciones puras.
+ *
+ * @module scripts/lib/jaccard-similarity
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+/** Longitud mínima de un token para ser considerado significativo. */
+const MIN_TOKEN_LENGTH = 3;
+
+/** Stop words en español que se excluyen del análisis. */
+const STOP_WORDS = new Set([
+  'que', 'los', 'las', 'del', 'una', 'por', 'con', 'para', 'como',
+  'sin', 'mas', 'sus', 'lo', 'le', 'la', 'el', 'al', 'no', 'es',
+  'se', 'de', 'en', 'un', 'a', 'y', 'o', 'pero', 'cuando',
+  'donde', 'porque', 'desde', 'hasta', 'sobre', 'bajo', 'entre',
+  'esta', 'este', 'esto', 'esa', 'ese', 'eso', 'tras', 'durante',
+  'mediante', 'segun', 'asi', 'tan', 'ya', 'aun', 'aunque',
+  // English equivalents (frequently mixed in technical text)
+  'the', 'and', 'for', 'with', 'this', 'that', 'have', 'from',
+  'are', 'was', 'will', 'not', 'has', 'had', 'but', 'can',
+]);
+
+// ── funciones puras ───────────────────────────────────────────────────────────
+
+/**
+ * Convierte un texto en un Set de tokens significativos (lowercase, sin stop
+ * words, longitud mínima). Preserva acentos.
+ *
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function tokenize(text) {
+  if (!text || typeof text !== 'string') return new Set();
+  return new Set(
+    String(text)
+      .toLowerCase()
+      .replace(/[`*_~\[\](){}<>#"'\-.,;:!?\/\\]/g, ' ')
+      .split(/\s+/)
+      .filter(t => t.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(t)),
+  );
+}
+
+/**
+ * Jaccard similarity entre dos Sets.
+ *
+ * @param {Set} setA
+ * @param {Set} setB
+ * @returns {number} en [0, 1]
+ */
+function jaccard(setA, setB) {
+  if (!(setA instanceof Set) || !(setB instanceof Set)) return 0;
+  if (setA.size === 0 && setB.size === 0) return 0;
+  if (setA.size === 0 || setB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection++;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Conveniencia: jaccard sobre dos textos.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} en [0, 1]
+ */
+function similarity(a, b) {
+  return jaccard(tokenize(a), tokenize(b));
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  tokenize,
+  jaccard,
+  similarity,
+  MIN_TOKEN_LENGTH,
+  STOP_WORDS,
+};

package/scripts/lib/longmemeval-runner.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * longmemeval-runner.js — Adapter que ejecuta queries del benchmark contra
+ * `hooks/lib/memory-search` y devuelve métricas.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Adaptado: en lugar de cargar haystack desde el dataset, usa el estado
+ * actual del proyecto SWL (APRENDIZAJES.md, sesiones, instintos).
+ *
+ * El dataset es un JSONL donde cada línea es:
+ * {
+ *   "question_id":  "q-001",
+ *   "question":     "texto libre de la query",
+ *   "gold_ids":     ["apr-N", "ses-YYYY-MM-DD-HHMM"],
+ *   "category":     "decision" | "patron" | "anti-patron" | "gotcha" | ...,
+ *   "status":       "real" | "placeholder"
+ * }
+ *
+ * @module scripts/lib/longmemeval-runner
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const memorySearch     = require('../../hooks/lib/memory-search');
+const benchmarkMetrics = require('./benchmark-metrics');
+
+// ── parser de dataset ─────────────────────────────────────────────────────────
+
+/**
+ * Parsea un archivo JSONL del dataset.
+ * @param {string} ruta
+ * @returns {object[]}
+ */
+function leerDataset(ruta) {
+  if (!fs.existsSync(ruta)) {
+    throw new Error(`Dataset no encontrado: ${ruta}`);
+  }
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  const entries = [];
+  let lineNum = 0;
+  for (const linea of contenido.split('\n')) {
+    lineNum++;
+    if (!linea.trim()) continue;
+    if (linea.trim().startsWith('//')) continue; // comentarios
+    try {
+      entries.push(JSON.parse(linea));
+    } catch (err) {
+      throw new Error(`JSONL malformado en línea ${lineNum}: ${err.message}`);
+    }
+  }
+  return entries;
+}
+
+// ── ejecución de query individual ─────────────────────────────────────────────
+
+/**
+ * Ejecuta una query del benchmark contra memoria SWL y compara con gold.
+ *
+ * @param {string} baseDir - Raíz del proyecto.
+ * @param {object} entry - Una línea del dataset.
+ * @param {object} [opts]
+ * @param {number} [opts.limit=20] - Top-k a recuperar.
+ * @returns {object} Métricas + ids retrieved + entry original.
+ */
+function ejecutarEntry(baseDir, entry, opts = {}) {
+  const limit = opts.limit || 20;
+  const inicio = Date.now();
+  const resultados = memorySearch.search(baseDir, entry.question, { limit });
+  const latencyMs = Date.now() - inicio;
+
+  const retrievedIds = resultados.map(r => r.id);
+  const goldIds = Array.isArray(entry.gold_ids) ? entry.gold_ids : [];
+  const metricas = benchmarkMetrics.calcularMetricas(retrievedIds, goldIds);
+
+  return {
+    question_id: entry.question_id || 'unknown',
+    question: entry.question,
+    category: entry.category || null,
+    status: entry.status || 'unknown',
+    retrievedIds,
+    goldIds,
+    metricas,
+    latencyMs,
+  };
+}
+
+/**
+ * Ejecuta el dataset completo y devuelve resultados + métricas agregadas.
+ *
+ * @param {string} baseDir
+ * @param {string} datasetPath
+ * @param {object} [opts]
+ * @returns {{ entries: object[], promedio: object, dataset: object }}
+ */
+function ejecutarDataset(baseDir, datasetPath, opts = {}) {
+  const entries = leerDataset(datasetPath);
+  const resultados = entries.map(e => ejecutarEntry(baseDir, e, opts));
+  const promedio = benchmarkMetrics.promediar(resultados.map(r => r.metricas));
+
+  // Estadísticas del dataset
+  const placeholderCount = entries.filter(e => e.status === 'placeholder').length;
+  const realCount = entries.filter(e => e.status === 'real').length;
+  const datasetMeta = {
+    total: entries.length,
+    real: realCount,
+    placeholder: placeholderCount,
+    significativo: realCount >= 30,
+  };
+
+  return {
+    entries: resultados,
+    promedio,
+    dataset: datasetMeta,
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  leerDataset,
+  ejecutarEntry,
+  ejecutarDataset,
+};

package/scripts/lib/rrf-fusion.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * rrf-fusion.js — Reciprocal Rank Fusion para combinar streams de búsqueda.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/state/hybrid-search.ts`. El
+ * algoritmo RRF combina rankings de múltiples sistemas de retrieval (BM25,
+ * vector, graph) sin requerir que sus scores sean comparables — solo importa
+ * la posición relativa (rank) en cada lista.
+ *
+ * Fórmula:
+ *
+ *     RRF(d) = Σ_i  w_i / (k + rank_i(d))
+ *
+ *   donde:
+ *     d         = un documento candidato
+ *     i         = índice del stream (BM25, vector, graph, ...)
+ *     w_i       = peso del stream i (default 1.0 si no se especifica)
+ *     rank_i(d) = posición 1-indexed de d en el stream i, o ∞ si no aparece
+ *     k         = constante de smoothing (default 60, estándar Cormack 2009)
+ *
+ * Propiedades:
+ *   - Robust frente a magnitudes de score heterogéneas — solo usa rank.
+ *   - Documentos que aparecen en múltiples streams reciben boost natural.
+ *   - Documentos que aparecen solo una vez no son penalizados — su rank ∞ en
+ *     otros streams contribuye 0.
+ *   - k ≈ 60 minimiza el peso de ranks bajos (< 60 efectivos).
+ *
+ * Versus suma simple de scores:
+ *   - No requiere normalización entre streams (BM25 vs vector cosine son
+ *     incomparables).
+ *   - Más resistente a outliers (un score muy alto en un stream no domina).
+ *
+ * Sin dependencias — Node stdlib only. Backward compatible: el caller puede
+ * mantener su lógica anterior y usar RRF solo cuando combine ≥2 streams.
+ *
+ * @module scripts/lib/rrf-fusion
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+/** Constante k del RRF estándar (Cormack et al., 2009). */
+const RRF_K_DEFAULT = 60;
+
+// ── funciones puras ───────────────────────────────────────────────────────────
+
+/**
+ * Construye un mapa `id → rank` desde un stream de resultados ordenados.
+ * Rank es 1-indexed: el primer elemento tiene rank 1.
+ * Si un id aparece varias veces, conserva el rank más bajo (mejor).
+ *
+ * @param {Array<{id: string}>} stream - Resultados ordenados (mejor primero).
+ * @returns {Map<string, number>} Mapa id → rank.
+ */
+function rankMap(stream) {
+  const map = new Map();
+  if (!Array.isArray(stream)) return map;
+  for (let i = 0; i < stream.length; i++) {
+    const item = stream[i];
+    if (!item || typeof item.id !== 'string') continue;
+    const rank = i + 1;
+    const previo = map.get(item.id);
+    if (previo === undefined || rank < previo) {
+      map.set(item.id, rank);
+    }
+  }
+  return map;
+}
+
+/**
+ * Score parcial del stream para un id dado.
+ * Si el id NO aparece en el stream, devuelve 0 (rank ∞).
+ *
+ * @param {Map<string, number>} map - Resultado de rankMap().
+ * @param {string} id
+ * @param {number} k
+ * @returns {number} contribución 1/(k + rank), o 0 si no aparece.
+ */
+function streamScore(map, id, k) {
+  const rank = map.get(id);
+  if (rank === undefined) return 0;
+  return 1 / (k + rank);
+}
+
+/**
+ * Reciprocal Rank Fusion: combina N streams de búsqueda en un ranking unificado.
+ *
+ * Cada stream es un array de objetos con al menos `{ id: string }`. La posición
+ * en el array determina el rank (1-indexed). Cualquier metadata extra (titulo,
+ * fecha, score, etc.) del primer stream donde aparece el id se preserva en el
+ * resultado.
+ *
+ * Si se proveen `weights`, se ponderan los streams. El array de pesos debe
+ * tener el mismo largo que `streams`. Si no se provee, todos los streams pesan
+ * 1.0. Pesos no positivos se tratan como 0 (efectivamente desactivan el stream).
+ *
+ * Si todos los pesos suman > 0, se normalizan a 1.0 para que el `combinedScore`
+ * resultante sea comparable entre invocaciones con distintos pesos.
+ *
+ * @param {Array<Array<object>>} streams - Lista de streams ordenados.
+ * @param {object} [opts]
+ * @param {number} [opts.k=60] - Constante k del RRF.
+ * @param {number[]} [opts.weights] - Pesos por stream (alineado con streams[]).
+ * @param {number} [opts.limit] - Limita la salida a N elementos top.
+ * @returns {Array<object>} Resultados combinados con `combinedScore`,
+ *   ordenados descendente. Conserva metadata del primer stream donde apareció
+ *   cada id.
+ */
+function rrfFusion(streams, opts = {}) {
+  if (!Array.isArray(streams) || streams.length === 0) return [];
+
+  const k = typeof opts.k === 'number' && opts.k > 0 ? opts.k : RRF_K_DEFAULT;
+
+  // Normalizar pesos
+  let weights;
+  if (Array.isArray(opts.weights) && opts.weights.length === streams.length) {
+    const positivos = opts.weights.map(w =>
+      typeof w === 'number' && w > 0 ? w : 0,
+    );
+    const total = positivos.reduce((a, b) => a + b, 0);
+    weights = total > 0 ? positivos.map(w => w / total) : positivos;
+  } else {
+    // Sin weights explícitos: todos iguales y normalizados (suman 1.0).
+    const efectivos = streams.filter(s => Array.isArray(s) && s.length > 0).length;
+    if (efectivos === 0) return [];
+    weights = streams.map(s =>
+      Array.isArray(s) && s.length > 0 ? 1 / efectivos : 0,
+    );
+  }
+
+  // Construir rankMap por stream + recolectar metadata por id
+  const maps = streams.map(rankMap);
+  const metadata = new Map(); // id → primer item visto
+
+  for (const stream of streams) {
+    if (!Array.isArray(stream)) continue;
+    for (const item of stream) {
+      if (!item || typeof item.id !== 'string') continue;
+      if (!metadata.has(item.id)) {
+        metadata.set(item.id, item);
+      }
+    }
+  }
+
+  // Calcular combinedScore para cada id
+  const combined = [];
+  for (const id of metadata.keys()) {
+    let score = 0;
+    for (let i = 0; i < streams.length; i++) {
+      score += weights[i] * streamScore(maps[i], id, k);
+    }
+    if (score > 0) {
+      combined.push({
+        ...metadata.get(id),
+        combinedScore: score,
+      });
+    }
+  }
+
+  combined.sort((a, b) => b.combinedScore - a.combinedScore);
+
+  if (typeof opts.limit === 'number' && opts.limit > 0) {
+    return combined.slice(0, opts.limit);
+  }
+  return combined;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  rrfFusion,
+  rankMap,
+  streamScore,
+  RRF_K_DEFAULT,
+};