@saulwade/swl-ses 1.1.4 → 1.2.0

package/scripts/benchmark-memoria.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * benchmark-memoria.js — CLI runner para benchmark de retrieval sobre memoria SWL.
+ *
+ * Ejecuta queries de un dataset JSONL contra `hooks/lib/memory-search`
+ * (que usa RRF fusion sobre aprendizajes/sesiones/instintos) y reporta
+ * métricas R@5, R@10, R@20, MRR, nDCG@10, P@5.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Adaptado para swl-ses: file-based, sin embeddings ML, dataset SWL-específico.
+ *
+ * Uso:
+ *   node scripts/benchmark-memoria.js [opciones]
+ *
+ * Opciones:
+ *   --dataset <ruta>   Dataset JSONL (default: .planning/benchmark/dataset.jsonl)
+ *   --limit <n>        Top-k a recuperar por query (default: 20)
+ *   --json             Output en JSON (para scripts)
+ *   --verbose          Detalle por query
+ *
+ * Exit codes:
+ *   0 - OK
+ *   1 - Error de I/O o dataset inválido
+ *   2 - Argumentos inválidos
+ *
+ * Persistencia opcional: si se setea SWL_BENCHMARK_PERSIST=1, escribe
+ * el resultado agregado a `.planning/evolucion/benchmark-memoria.jsonl`
+ * para tracking histórico.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { ejecutarDataset } = require('./lib/longmemeval-runner');
+
+const DATASET_DEFAULT = '.planning/benchmark/dataset.jsonl';
+const HISTORICO_PATH  = '.planning/evolucion/benchmark-memoria.jsonl';
+
+function uso() {
+  console.error('Uso: node scripts/benchmark-memoria.js [--dataset <ruta>] [--limit <n>] [--json] [--verbose]');
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    dataset: DATASET_DEFAULT,
+    limit: 20,
+    json: false,
+    verbose: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--dataset') opts.dataset = argv[++i];
+    else if (arg === '--limit') opts.limit = parseInt(argv[++i], 10) || 20;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--verbose') opts.verbose = true;
+    else if (arg === '--help' || arg === '-h') uso();
+  }
+  return opts;
+}
+
+function persistirHistorico(baseDir, resumen) {
+  if (process.env.SWL_BENCHMARK_PERSIST !== '1') return;
+  try {
+    const dirEvolucion = path.join(baseDir, '.planning', 'evolucion');
+    if (!fs.existsSync(dirEvolucion)) fs.mkdirSync(dirEvolucion, { recursive: true });
+    const linea = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      ...resumen,
+    });
+    fs.appendFileSync(path.join(baseDir, HISTORICO_PATH), linea + '\n', 'utf8');
+  } catch (_) {
+    // best-effort
+  }
+}
+
+function reportarTexto(resultado, opts) {
+  const { promedio, dataset, entries } = resultado;
+
+  console.log('================================================================');
+  console.log('   Benchmark de retrieval de memoria SWL');
+  console.log('================================================================');
+  console.log('');
+  console.log(`Dataset:      ${opts.dataset}`);
+  console.log(`Total queries: ${dataset.total}`);
+  console.log(`  Reales:      ${dataset.real}`);
+  console.log(`  Placeholder: ${dataset.placeholder}`);
+  console.log(`Significativo: ${dataset.significativo ? 'sí' : 'NO (requiere ≥30 reales)'}`);
+  console.log('');
+
+  if (!dataset.significativo) {
+    console.log('⚠ ADVERTENCIA: dataset con menos de 30 queries reales.');
+    console.log('  Las métricas son INDICATIVAS, no estadísticamente significativas.');
+    console.log('  Para usar como gate de release, expandir el dataset con preguntas');
+    console.log('  curadas extraídas de uso real (ver SKILL.md de benchmark-memoria).');
+    console.log('');
+  }
+
+  console.log('────────────── Métricas agregadas ──────────────');
+  console.log(`  Recall @ 5:     ${(promedio.recall_at_5 * 100).toFixed(1)}%`);
+  console.log(`  Recall @ 10:    ${(promedio.recall_at_10 * 100).toFixed(1)}%`);
+  console.log(`  Recall @ 20:    ${(promedio.recall_at_20 * 100).toFixed(1)}%`);
+  console.log(`  MRR:            ${promedio.mrr.toFixed(3)}`);
+  console.log(`  nDCG @ 10:      ${promedio.ndcg_at_10.toFixed(3)}`);
+  console.log(`  Precision @ 5:  ${(promedio.precision_at_5 * 100).toFixed(1)}%`);
+  console.log('');
+
+  if (opts.verbose) {
+    console.log('────────────── Detalle por query ──────────────');
+    for (const r of entries) {
+      const mark = r.metricas.recall_at_5 > 0 ? '✓' : '✗';
+      console.log(`  ${mark} ${r.question_id} [${r.category || 'n/a'}, ${r.status}] ` +
+        `R@5=${r.metricas.recall_at_5} R@10=${r.metricas.recall_at_10} ` +
+        `MRR=${r.metricas.mrr.toFixed(2)} (${r.latencyMs}ms)`);
+      if (r.metricas.recall_at_5 === 0 && opts.verbose) {
+        console.log(`      Q: ${r.question.slice(0, 80)}`);
+        console.log(`      Gold:      ${r.goldIds.slice(0, 3).join(', ')}${r.goldIds.length > 3 ? '...' : ''}`);
+        console.log(`      Retrieved: ${r.retrievedIds.slice(0, 5).join(', ')}`);
+      }
+    }
+    console.log('');
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const baseDir = process.cwd();
+
+  if (!fs.existsSync(opts.dataset)) {
+    console.error(`Dataset no encontrado: ${opts.dataset}`);
+    console.error(`Crea uno o usa el placeholder en ${DATASET_DEFAULT}.`);
+    process.exit(1);
+  }
+
+  let resultado;
+  try {
+    resultado = ejecutarDataset(baseDir, opts.dataset, { limit: opts.limit });
+  } catch (err) {
+    console.error(`Error ejecutando benchmark: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(resultado, null, 2));
+  } else {
+    reportarTexto(resultado, opts);
+  }
+
+  persistirHistorico(baseDir, {
+    dataset: opts.dataset,
+    n: resultado.dataset.total,
+    significativo: resultado.dataset.significativo,
+    promedio: resultado.promedio,
+  });
+
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseArgs,
+};

package/scripts/detectar-aprendizajes-duplicados.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * detectar-aprendizajes-duplicados.js
+ *
+ * Detecta pares de entradas en `.planning/APRENDIZAJES.md` con alta similitud
+ * de tokens (Jaccard > umbral). Útil para identificar candidatos a fusionar
+ * cuando el hook de auto-extracción genera entradas redundantes.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/functions/auto-forget.ts`
+ * (contradiction detection con Jaccard >= 0.9). Aquí se usa con threshold
+ * configurable más bajo (0.6 default) porque queremos sugerir, no auto-borrar.
+ *
+ * NO modifica APRENDIZAJES.md. Solo reporta. La acción de fusión queda en
+ * manos del usuario o de un comando separado (`/swl:aprender consolidar`).
+ *
+ * Uso:
+ *   node scripts/detectar-aprendizajes-duplicados.js [threshold]
+ *
+ * Argumentos:
+ *   threshold  - Similitud mínima para reportar (default: 0.6, rango [0, 1]).
+ *
+ * Exit codes:
+ *   0 - Ejecución OK (haya o no duplicados)
+ *   1 - Error de I/O o parseo
+ *
+ * Output: tabla legible en stdout. Si se detectan ≥ 1 duplicados, también
+ * imprime sugerencia para revisar/consolidar.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { tokenize, jaccard } = require('./lib/jaccard-similarity');
+
+const RUTA_APRENDIZAJES = path.join(process.cwd(), '.planning', 'APRENDIZAJES.md');
+const DEFAULT_THRESHOLD = 0.6;
+const MAX_PARES_REPORTADOS = 30;
+
+function parsearEntradas(contenido) {
+  const lineas = contenido.split('\n');
+  const entradas = [];
+  let actual = null;
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+    if (linea.startsWith('## ')) {
+      if (actual) entradas.push(actual);
+      actual = {
+        lineaInicio: i + 1,
+        titulo: linea.slice(3).trim(),
+        contenido: '',
+      };
+    } else if (actual) {
+      actual.contenido += linea + '\n';
+    }
+  }
+  if (actual) entradas.push(actual);
+
+  // Filtrar entradas vacías o triviales (< 50 chars de contenido real)
+  return entradas.filter(e => e.contenido.replace(/\s/g, '').length >= 50);
+}
+
+function detectarDuplicados(entradas, threshold) {
+  const tokensCache = entradas.map(e => tokenize(e.titulo + ' ' + e.contenido));
+  const pares = [];
+
+  for (let i = 0; i < entradas.length; i++) {
+    for (let j = i + 1; j < entradas.length; j++) {
+      const sim = jaccard(tokensCache[i], tokensCache[j]);
+      if (sim >= threshold) {
+        pares.push({
+          entradaA: entradas[i],
+          entradaB: entradas[j],
+          similitud: sim,
+        });
+      }
+    }
+  }
+
+  pares.sort((a, b) => b.similitud - a.similitud);
+  return pares;
+}
+
+function reportarTexto(pares) {
+  if (pares.length === 0) {
+    console.log('Sin duplicados detectados sobre el umbral.');
+    return;
+  }
+
+  console.log(`Pares con similitud Jaccard ≥ umbral: ${pares.length}`);
+  console.log('');
+
+  const limite = Math.min(pares.length, MAX_PARES_REPORTADOS);
+  for (let i = 0; i < limite; i++) {
+    const p = pares[i];
+    console.log(`  [${(p.similitud * 100).toFixed(1)}%] ` +
+      `L${p.entradaA.lineaInicio} ↔ L${p.entradaB.lineaInicio}`);
+    console.log('         A: ' + p.entradaA.titulo.slice(0, 80));
+    console.log('         B: ' + p.entradaB.titulo.slice(0, 80));
+    console.log('');
+  }
+
+  if (pares.length > limite) {
+    console.log(`  ... ${pares.length - limite} pares adicionales no mostrados`);
+  }
+
+  console.log('Sugerencia: revisa los pares con mayor similitud y considera ' +
+    'fusionarlos en una sola entrada con `/swl:aprender consolidar` o manualmente.');
+}
+
+function main() {
+  const threshold = parseFloat(process.argv[2]) || DEFAULT_THRESHOLD;
+
+  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+    console.error(`Threshold inválido: ${process.argv[2]}. Usar valor en [0, 1].`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(RUTA_APRENDIZAJES)) {
+    console.error(`No existe ${RUTA_APRENDIZAJES}.`);
+    process.exit(1);
+  }
+
+  let contenido;
+  try {
+    contenido = fs.readFileSync(RUTA_APRENDIZAJES, 'utf8');
+  } catch (err) {
+    console.error(`Error leyendo ${RUTA_APRENDIZAJES}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const entradas = parsearEntradas(contenido);
+  console.log(`Entradas encontradas: ${entradas.length}`);
+  console.log(`Threshold de similitud: ${threshold}`);
+  console.log('');
+
+  const pares = detectarDuplicados(entradas, threshold);
+  reportarTexto(pares);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parsearEntradas,
+  detectarDuplicados,
+  reportarTexto,
+};

package/scripts/lib/benchmark-metrics.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * benchmark-metrics.js — Métricas de retrieval para benchmark de memoria SWL.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/benchmark/longmemeval-bench.ts`.
+ * Funciones puras zero-deps. Adaptado a IDs SWL (aprendizaje, sesion,
+ * instinto) en lugar de session_id de agentmemory.
+ *
+ * Métricas:
+ *   - recallAt(k): 1.0 si al menos un gold ID está en los top-k, sino 0.0
+ *   - precisionAt(k): proporción de top-k que son gold
+ *   - mrr: Mean Reciprocal Rank (1/rank del primer gold encontrado)
+ *   - ndcgAt(k): Normalized Discounted Cumulative Gain
+ *
+ * @module scripts/lib/benchmark-metrics
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function asSet(arr) {
+  return new Set(Array.isArray(arr) ? arr : []);
+}
+
+// ── métricas individuales ─────────────────────────────────────────────────────
+
+/**
+ * Recall @ k: 1.0 si ALGÚN id gold está en los primeros k retrieved.
+ *
+ * @param {string[]} retrievedIds - IDs ordenados (mejor primero).
+ * @param {string[]} goldIds - IDs correctos esperados.
+ * @param {number} k
+ * @returns {number} 0 o 1
+ */
+function recallAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const topK = new Set(retrievedIds.slice(0, k));
+  return goldIds.some(g => topK.has(g)) ? 1.0 : 0.0;
+}
+
+/**
+ * Precision @ k: proporción de los primeros k retrieved que son gold.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function precisionAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const topK = retrievedIds.slice(0, k);
+  if (topK.length === 0) return 0;
+  const hits = topK.filter(id => goldSet.has(id)).length;
+  return hits / topK.length;
+}
+
+/**
+ * Mean Reciprocal Rank: 1/rank del primer gold encontrado, o 0 si ninguno.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {number} en [0, 1]
+ */
+function mrr(retrievedIds, goldIds) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds)) return 0;
+  const goldSet = asSet(goldIds);
+  for (let i = 0; i < retrievedIds.length; i++) {
+    if (goldSet.has(retrievedIds[i])) {
+      return 1 / (i + 1);
+    }
+  }
+  return 0;
+}
+
+function dcg(relevancias, k) {
+  let suma = 0;
+  for (let i = 0; i < Math.min(k, relevancias.length); i++) {
+    suma += (relevancias[i] ? 1 : 0) / Math.log2(i + 2);
+  }
+  return suma;
+}
+
+/**
+ * Normalized Discounted Cumulative Gain @ k.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @param {number} k
+ * @returns {number} en [0, 1]
+ */
+function ndcgAt(retrievedIds, goldIds, k) {
+  if (!Array.isArray(retrievedIds) || !Array.isArray(goldIds) || k <= 0) return 0;
+  const goldSet = asSet(goldIds);
+  const rels = retrievedIds.slice(0, k).map(id => goldSet.has(id));
+  const idealRels = Array.from({ length: Math.min(k, goldSet.size) }, () => true);
+  const idealDCG = dcg(idealRels, k);
+  if (idealDCG === 0) return 0;
+  return dcg(rels, k) / idealDCG;
+}
+
+// ── agregados ─────────────────────────────────────────────────────────────────
+
+/**
+ * Calcula el conjunto completo de métricas para una query.
+ *
+ * @param {string[]} retrievedIds
+ * @param {string[]} goldIds
+ * @returns {{ recall_at_5, recall_at_10, recall_at_20, mrr, ndcg_at_10, precision_at_5 }}
+ */
+function calcularMetricas(retrievedIds, goldIds) {
+  return {
+    recall_at_5:    recallAt(retrievedIds, goldIds, 5),
+    recall_at_10:   recallAt(retrievedIds, goldIds, 10),
+    recall_at_20:   recallAt(retrievedIds, goldIds, 20),
+    mrr:            mrr(retrievedIds, goldIds),
+    ndcg_at_10:     ndcgAt(retrievedIds, goldIds, 10),
+    precision_at_5: precisionAt(retrievedIds, goldIds, 5),
+  };
+}
+
+/**
+ * Promedia métricas sobre múltiples queries.
+ *
+ * @param {Array<object>} resultados - Array de objetos producidos por calcularMetricas().
+ * @returns {object} Promedios con campo `n` (cantidad de queries).
+ */
+function promediar(resultados) {
+  if (!Array.isArray(resultados) || resultados.length === 0) {
+    return {
+      n: 0,
+      recall_at_5: 0,
+      recall_at_10: 0,
+      recall_at_20: 0,
+      mrr: 0,
+      ndcg_at_10: 0,
+      precision_at_5: 0,
+    };
+  }
+
+  const claves = ['recall_at_5', 'recall_at_10', 'recall_at_20', 'mrr', 'ndcg_at_10', 'precision_at_5'];
+  const promedio = { n: resultados.length };
+  for (const k of claves) {
+    const sum = resultados.reduce((a, r) => a + (r[k] || 0), 0);
+    promedio[k] = sum / resultados.length;
+  }
+  return promedio;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  recallAt,
+  precisionAt,
+  mrr,
+  ndcgAt,
+  dcg,
+  calcularMetricas,
+  promediar,
+};

package/scripts/lib/eval-metrics-store.js

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * eval-metrics-store.js — Persistencia agregada de métricas de evaluación.
+ *
+ * Patrón adoptado de `temp/agentmemory-main/src/eval/metrics-store.ts`.
+ * Adaptado a swl-ses: file-based en lugar de SQLite. Persiste:
+ *   - JSONL append-only:    `.planning/evolucion/eval-results.jsonl` (cada eval individual)
+ *   - JSON agregado:        `.planning/evolucion/eval-metrics.json`  (totales por functionId)
+ *
+ * El JSONL preserva el detalle histórico (un evento por evaluación). El JSON
+ * agregado se recalcula incrementalmente: avg latency, avg quality, success
+ * rate por functionId. Lectura barata sin escanear todo el JSONL.
+ *
+ * Funciones puras donde es posible. Las funciones I/O usan escrituras atómicas
+ * (atomicWriteJSON) para `eval-metrics.json`. El JSONL usa appendFileSync
+ * (regla SWL: JSONL para alta frecuencia).
+ *
+ * @module scripts/lib/eval-metrics-store
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('../../hooks/lib/atomic-write'));
+} catch {
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+const DIR_EVOLUCION = path.join('.planning', 'evolucion');
+const RUTA_JSONL    = path.join(DIR_EVOLUCION, 'eval-results.jsonl');
+const RUTA_AGREGADO = path.join(DIR_EVOLUCION, 'eval-metrics.json');
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function asegurarDir(baseDir) {
+  const dir = path.join(baseDir, DIR_EVOLUCION);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function leerAgregado(baseDir) {
+  const ruta = path.join(baseDir, RUTA_AGREGADO);
+  if (!fs.existsSync(ruta)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(ruta, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Registra una evaluación completada.
+ *
+ * Append-only al JSONL + actualización incremental del agregado.
+ *
+ * @param {string} baseDir - Raíz del proyecto.
+ * @param {object} evento
+ * @param {string} evento.functionId - Identificador de la función evaluada.
+ * @param {number} evento.latencyMs
+ * @param {boolean} evento.success
+ * @param {number} [evento.qualityScore] - en [0, 100]
+ * @param {object} [evento.metadata]
+ * @returns {{ recorded: boolean, error?: string }}
+ */
+function registrar(baseDir, evento) {
+  if (!evento || typeof evento.functionId !== 'string') {
+    return { recorded: false, error: 'functionId requerido' };
+  }
+
+  asegurarDir(baseDir);
+
+  const ts = new Date().toISOString();
+  const lineaJSONL = JSON.stringify({
+    timestamp: ts,
+    functionId: evento.functionId,
+    latencyMs: typeof evento.latencyMs === 'number' ? evento.latencyMs : 0,
+    success: Boolean(evento.success),
+    qualityScore: typeof evento.qualityScore === 'number' ? evento.qualityScore : null,
+    metadata: evento.metadata || null,
+  });
+
+  try {
+    fs.appendFileSync(path.join(baseDir, RUTA_JSONL), lineaJSONL + '\n', 'utf8');
+  } catch (err) {
+    return { recorded: false, error: 'JSONL append failed: ' + err.message };
+  }
+
+  // Actualizar agregado
+  try {
+    const agregado = leerAgregado(baseDir);
+    const fid = evento.functionId;
+    const m = agregado[fid] || {
+      functionId: fid,
+      totalCalls: 0,
+      successCount: 0,
+      failureCount: 0,
+      avgLatencyMs: 0,
+      avgQualityScore: 0,
+      qualityCallCounts: 0,
+      lastUpdatedAt: ts,
+    };
+
+    const prev = m.totalCalls;
+    m.totalCalls += 1;
+    m.avgLatencyMs = (m.avgLatencyMs * prev + (evento.latencyMs || 0)) / m.totalCalls;
+    if (evento.success) m.successCount += 1;
+    else m.failureCount += 1;
+
+    if (typeof evento.qualityScore === 'number') {
+      const prevQ = m.qualityCallCounts || 0;
+      m.avgQualityScore = (m.avgQualityScore * prevQ + evento.qualityScore) / (prevQ + 1);
+      m.qualityCallCounts = prevQ + 1;
+    }
+
+    m.lastUpdatedAt = ts;
+    agregado[fid] = m;
+    atomicWriteJSON(path.join(baseDir, RUTA_AGREGADO), agregado);
+  } catch (err) {
+    return { recorded: true, error: 'Aggregate update failed: ' + err.message };
+  }
+
+  return { recorded: true };
+}
+
+/**
+ * Lee las métricas agregadas para un functionId específico.
+ * @param {string} baseDir
+ * @param {string} functionId
+ * @returns {object|null}
+ */
+function obtener(baseDir, functionId) {
+  const agregado = leerAgregado(baseDir);
+  return agregado[functionId] || null;
+}
+
+/**
+ * Lee todas las métricas agregadas.
+ * @param {string} baseDir
+ * @returns {object[]}
+ */
+function obtenerTodos(baseDir) {
+  const agregado = leerAgregado(baseDir);
+  return Object.values(agregado);
+}
+
+/**
+ * Recorre el JSONL y reconstruye el agregado desde cero.
+ * Útil tras corrupción del agregado o auditoría histórica.
+ *
+ * @param {string} baseDir
+ * @returns {{ rebuilt: number, functions: number }}
+ */
+function reconstruirAgregado(baseDir) {
+  const ruta = path.join(baseDir, RUTA_JSONL);
+  if (!fs.existsSync(ruta)) return { rebuilt: 0, functions: 0 };
+
+  const agregado = {};
+  let lineas = 0;
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  for (const linea of contenido.split('\n')) {
+    if (!linea.trim()) continue;
+    let evento;
+    try { evento = JSON.parse(linea); } catch { continue; }
+
+    const fid = evento.functionId;
+    if (!fid) continue;
+    lineas++;
+
+    const m = agregado[fid] || {
+      functionId: fid,
+      totalCalls: 0,
+      successCount: 0,
+      failureCount: 0,
+      avgLatencyMs: 0,
+      avgQualityScore: 0,
+      qualityCallCounts: 0,
+      lastUpdatedAt: evento.timestamp,
+    };
+
+    const prev = m.totalCalls;
+    m.totalCalls += 1;
+    m.avgLatencyMs = (m.avgLatencyMs * prev + (evento.latencyMs || 0)) / m.totalCalls;
+    if (evento.success) m.successCount += 1;
+    else m.failureCount += 1;
+
+    if (typeof evento.qualityScore === 'number') {
+      const prevQ = m.qualityCallCounts || 0;
+      m.avgQualityScore = (m.avgQualityScore * prevQ + evento.qualityScore) / (prevQ + 1);
+      m.qualityCallCounts = prevQ + 1;
+    }
+
+    m.lastUpdatedAt = evento.timestamp;
+    agregado[fid] = m;
+  }
+
+  asegurarDir(baseDir);
+  atomicWriteJSON(path.join(baseDir, RUTA_AGREGADO), agregado);
+  return { rebuilt: lineas, functions: Object.keys(agregado).length };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  registrar,
+  obtener,
+  obtenerTodos,
+  reconstruirAgregado,
+  RUTA_JSONL,
+  RUTA_AGREGADO,
+};