@saulwade/swl-ses 1.0.0

package/scripts/lib/drift-detector.js

@@ -0,0 +1,545 @@
+'use strict';
+
+/**
+ * drift-detector.js
+ *
+ * Detector de drift para el ciclo AGP de swl-ses.
+ *
+ * Algoritmo de ventana deslizante (7 días recientes) vs baseline (4 semanas
+ * previas) que identifica degradación de skills y agentes antes de que el
+ * health score lo refleje.
+ *
+ * Adaptado de `runDriftCheck` y `getDriftTimeline` en:
+ *   temp/mission-control-main/src/lib/agent-evals.ts (líneas 188-345)
+ *   Licencia: MIT — Builderz Labs
+ *
+ * Diferencias respecto al original:
+ *   - Fuente de datos: JSONL en disco, no SQLite
+ *   - Sin dependencias externas (solo Node stdlib: fs, path)
+ *   - Métricas configurables via parámetro, no hardcodeadas
+ *   - Emite nudge a .planning/evolucion/nudges.jsonl en drift crítico
+ *
+ * @module scripts/lib/drift-detector
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+const UMBRAL_DEFAULT_PCT       = 10;   // warn si drift > 10%
+const VENTANA_DIAS_DEFAULT     = 7;
+const BASELINE_SEMANAS_DEFAULT = 4;
+const DIAS_LINEA_DEFAULT       = 30;
+
+/**
+ * Umbral de repair-loop: tras N nudges sucesivos del mismo (metrica, agente)
+ * sin accionar, banear el par para no saturar nudges.jsonl.
+ * Patrón adaptado de evolver GEP (temp/evolver-main/src/config.js:74-88).
+ */
+const REPAIR_LOOP_THRESHOLD = parseInt(process.env.SWL_REPAIR_LOOP_THRESHOLD || '3', 10);
+
+/** Ventana para contar repeticiones sin accionar (ms). */
+const REPAIR_LOOP_WINDOW_MS = 14 * 24 * 3600 * 1000;
+
+const METRICAS_DEFAULT = [
+  'tokens_promedio_por_sesion',
+  'tasa_exito_tool',
+  'tasa_finalizacion_tarea',
+];
+
+// Ruta raíz del proyecto (dos niveles arriba de scripts/lib/)
+const RAIZ_PROYECTO = path.resolve(__dirname, '..', '..');
+const RUTA_NUDGES   = path.join(RAIZ_PROYECTO, '.planning', 'evolucion', 'nudges.jsonl');
+
+// ── helpers internos ──────────────────────────────────────────────────────────
+
+/**
+ * Lee y parsea un archivo JSONL. Filtra líneas vacías y JSON inválido.
+ *
+ * @param {string} ruta - Ruta absoluta al archivo JSONL.
+ * @returns {object[]} Array de objetos parseados.
+ * @throws {Error} Si el archivo no existe o no es legible.
+ */
+function leerJsonl(ruta) {
+  if (!fs.existsSync(ruta)) {
+    throw new Error(`JSONL no encontrado: ${ruta}`);
+  }
+  const contenido = fs.readFileSync(ruta, 'utf8');
+  return contenido
+    .split('\n')
+    .filter(l => l.trim().length > 0)
+    .reduce((acc, linea) => {
+      try {
+        acc.push(JSON.parse(linea));
+      } catch (_) {
+        // línea malformada — ignorar silenciosamente
+      }
+      return acc;
+    }, []);
+}
+
+/**
+ * Convierte un timestamp ISO o epoch-segundos a epoch-milisegundos.
+ *
+ * @param {string|number} ts
+ * @returns {number} timestamp en ms, o NaN si inválido.
+ */
+function aMs(ts) {
+  if (!ts) return NaN;
+  if (typeof ts === 'number') {
+    // Si viene en segundos (< año 3000 en segundos), convertir a ms
+    return ts < 32503680000 ? ts * 1000 : ts;
+  }
+  return new Date(ts).getTime();
+}
+
+/**
+ * Calcula métricas agregadas de un conjunto de eventos.
+ *
+ * @param {object[]} eventos
+ * @param {string[]} metricas - Lista de nombres de métrica a calcular.
+ * @returns {object} Mapa metrica → valor calculado (0 si sin datos).
+ */
+function calcularMetricas(eventos, metricas) {
+  const resultado = {};
+
+  if (metricas.includes('tokens_promedio_por_sesion')) {
+    const coTokens = eventos.filter(e => {
+      const t = e.atributos?.tokens_totales ?? e.tokens ?? e.total_tokens;
+      return typeof t === 'number';
+    });
+    resultado.tokens_promedio_por_sesion = coTokens.length > 0
+      ? coTokens.reduce((s, e) => {
+          const t = e.atributos?.tokens_totales ?? e.tokens ?? e.total_tokens ?? 0;
+          return s + t;
+        }, 0) / coTokens.length
+      : 0;
+  }
+
+  if (metricas.includes('tasa_exito_tool')) {
+    const conExito = eventos.filter(e => {
+      const s = e.success ?? e.exito ?? e.atributos?.success;
+      return s !== undefined && s !== null;
+    });
+    if (conExito.length > 0) {
+      const exitosos = conExito.filter(e => {
+        const s = e.success ?? e.exito ?? e.atributos?.success;
+        return s === true || s === 1 || s === 'true';
+      }).length;
+      resultado.tasa_exito_tool = exitosos / conExito.length;
+    } else {
+      resultado.tasa_exito_tool = 1.0; // sin datos → asumir 100%
+    }
+  }
+
+  if (metricas.includes('tasa_finalizacion_tarea')) {
+    const conEstado = eventos.filter(e => {
+      const st = e.estado ?? e.status ?? e.atributos?.estado;
+      return st !== undefined && st !== null;
+    });
+    if (conEstado.length > 0) {
+      const terminadas = conEstado.filter(e => {
+        const st = String(e.estado ?? e.status ?? e.atributos?.estado ?? '').toLowerCase();
+        return st === 'ok' || st === 'done' || st === 'completado' || st === 'complete';
+      }).length;
+      resultado.tasa_finalizacion_tarea = terminadas / conEstado.length;
+    } else {
+      resultado.tasa_finalizacion_tarea = 1.0;
+    }
+  }
+
+  return resultado;
+}
+
+/**
+ * Determina el estado de drift para un porcentaje dado.
+ *
+ * @param {number} driftPct
+ * @param {number} umbralPct
+ * @returns {'ok'|'warn'|'critico'}
+ */
+function estadoDrift(driftPct, umbralPct) {
+  const abs = Math.abs(driftPct);
+  if (abs > umbralPct * 2) return 'critico';
+  if (abs > umbralPct)     return 'warn';
+  return 'ok';
+}
+
+/**
+ * Cuenta nudges previos tipo 'drift-detectado' del mismo (metrica, agente)
+ * no accionados dentro de la ventana. Zero-deps, lectura lineal.
+ *
+ * @param {string} metrica
+ * @param {string} agente
+ * @returns {number} cantidad de nudges no accionados en la ventana
+ */
+function contarNudgesPrevios(metrica, agente) {
+  if (!fs.existsSync(RUTA_NUDGES)) return 0;
+  let contenido;
+  try {
+    contenido = fs.readFileSync(RUTA_NUDGES, 'utf8');
+  } catch {
+    return 0;
+  }
+  const limiteMs = Date.now() - REPAIR_LOOP_WINDOW_MS;
+  let conteo = 0;
+  for (const linea of contenido.split(/\r?\n/)) {
+    if (!linea.trim()) continue;
+    let ev;
+    try { ev = JSON.parse(linea); } catch { continue; }
+    const esDrift = ev.tipo === 'drift-detectado' || ev.kind === 'drift-detectado';
+    if (!esDrift) continue;
+    const mismaMetrica = ev.metrica === metrica;
+    const mismoAgente = (ev.agente_o_skill === agente) || (ev.target === agente);
+    if (!mismaMetrica || !mismoAgente) continue;
+    if (ev.accionado === true) continue;
+    const t = Date.parse(ev.timestamp || ev.ts || '');
+    if (!Number.isFinite(t) || t < limiteMs) continue;
+    conteo++;
+  }
+  return conteo;
+}
+
+/**
+ * Emite un nudge a .planning/evolucion/nudges.jsonl cuando se detecta
+ * drift crítico. Usa fs.appendFileSync (JSONL, no sobreescribe).
+ *
+ * Aplica repair-loop detection: si el mismo (metrica, agente) ya fue
+ * emitido ≥ REPAIR_LOOP_THRESHOLD veces sin accionar en la ventana,
+ * el nudge se marca como `banned: true` para inspección diagnóstica
+ * pero no se emite a stderr. Esto evita saturar el log ante drift
+ * persistente ignorado.
+ *
+ * @param {string} metrica
+ * @param {number} driftPct
+ * @param {string} [agente]
+ * @returns {{emitido: boolean, banned: boolean, previos: number}}
+ */
+function emitirNudgeDrift(metrica, driftPct, agente) {
+  const agenteNormalizado = agente || 'desconocido';
+  const previos = contarNudgesPrevios(metrica, agenteNormalizado);
+  const banned = previos >= REPAIR_LOOP_THRESHOLD;
+
+  const nudge = {
+    timestamp:         new Date().toISOString(),
+    tipo:              'drift-detectado',
+    agente_o_skill:    agenteNormalizado,
+    metrica,
+    drift_pct:         Math.round(driftPct * 100) / 100,
+    estado:            'critico',
+    previos_ventana:   previos,
+  };
+  if (banned) nudge.banned = true;
+
+  try {
+    fs.appendFileSync(RUTA_NUDGES, JSON.stringify(nudge) + '\n', 'utf8');
+  } catch (_) {
+    // No crashear si la carpeta no existe
+  }
+  return { emitido: !banned, banned, previos };
+}
+
+// ── exports públicos ──────────────────────────────────────────────────────────
+
+/**
+ * Detecta drift comparando una ventana reciente contra un baseline histórico.
+ *
+ * Lee el JSONL indicado, divide los eventos en dos ventanas temporales y
+ * calcula el porcentaje de variación por métrica. Emite nudge automático
+ * si algún drift es crítico.
+ *
+ * @param {object} opts
+ * @param {string}   opts.rutaJsonl             - Ruta absoluta al archivo JSONL de eventos.
+ * @param {number}   [opts.ventanaDias=7]        - Tamaño de la ventana reciente en días.
+ * @param {number}   [opts.baselineSemanasBase=4] - Semanas de baseline previas a la ventana.
+ * @param {number}   [opts.umbralPct=10]          - Umbral de alerta (warn si drift > umbralPct%).
+ * @param {string[]} [opts.metricas]              - Métricas a calcular (ver METRICAS_DEFAULT).
+ * @param {string}   [opts.agente]                - Nombre del agente/skill (para nudges).
+ * @returns {{
+ *   drifts: Array<{metrica:string, baseline:number, reciente:number, driftPct:number, estado:string}>,
+ *   timestamp: string,
+ *   estado_global: 'ok'|'warn'|'critico'
+ * }}
+ */
+function detectarDrift({
+  rutaJsonl,
+  ventanaDias        = VENTANA_DIAS_DEFAULT,
+  baselineSemanasBase = BASELINE_SEMANAS_DEFAULT,
+  umbralPct          = UMBRAL_DEFAULT_PCT,
+  metricas           = METRICAS_DEFAULT,
+  agente,
+} = {}) {
+  let eventos;
+  try {
+    eventos = leerJsonl(rutaJsonl);
+  } catch (err) {
+    return {
+      drifts:        [],
+      timestamp:     new Date().toISOString(),
+      estado_global: 'ok',
+      error:         err.message,
+    };
+  }
+
+  const ahora          = Date.now();
+  const msVentana      = ventanaDias * 24 * 3600 * 1000;
+  const msBaseline     = baselineSemanasBase * 7 * 24 * 3600 * 1000;
+
+  const inicioVentana  = ahora - msVentana;
+  const inicioBaseline = ahora - msBaseline - msVentana;
+  const finBaseline    = inicioVentana;
+
+  const eventosRecientes = eventos.filter(e => {
+    const ms = aMs(e.timestamp ?? e.ts ?? e.inicio ?? e.created_at);
+    return !isNaN(ms) && ms >= inicioVentana && ms <= ahora;
+  });
+
+  const eventosBaseline = eventos.filter(e => {
+    const ms = aMs(e.timestamp ?? e.ts ?? e.inicio ?? e.created_at);
+    return !isNaN(ms) && ms >= inicioBaseline && ms < finBaseline;
+  });
+
+  const metricasRecientes = calcularMetricas(eventosRecientes, metricas);
+  const metricasBaseline  = calcularMetricas(eventosBaseline,  metricas);
+
+  const drifts = metricas.map(m => {
+    const base   = metricasBaseline[m]  ?? 0;
+    const actual = metricasRecientes[m] ?? 0;
+
+    let driftPct;
+    if (base !== 0) {
+      driftPct = (actual - base) / Math.abs(base) * 100;
+    } else {
+      driftPct = actual !== 0 ? 100 : 0;
+    }
+    driftPct = Math.round(driftPct * 100) / 100;
+
+    const estado = estadoDrift(driftPct, umbralPct);
+    return { metrica: m, baseline: base, reciente: actual, driftPct, estado };
+  });
+
+  // Emitir nudge por cada métrica crítica
+  for (const d of drifts) {
+    if (d.estado === 'critico') {
+      emitirNudgeDrift(d.metrica, d.driftPct, agente);
+    }
+  }
+
+  const estado_global = drifts.some(d => d.estado === 'critico') ? 'critico'
+    : drifts.some(d => d.estado === 'warn')    ? 'warn'
+    : 'ok';
+
+  return {
+    drifts,
+    timestamp:     new Date().toISOString(),
+    estado_global,
+  };
+}
+
+/**
+ * Genera una línea temporal diaria de métricas agregadas para visualización.
+ *
+ * Para cada uno de los últimos `dias` días calcula tokens, éxitos y fallos
+ * acumulados en ese día.
+ *
+ * @param {object} opts
+ * @param {string} opts.rutaJsonl       - Ruta absoluta al archivo JSONL de eventos.
+ * @param {number} [opts.ventanaDias=7] - No usado en este export; reservado para consistencia API.
+ * @param {number} [opts.dias=30]       - Cantidad de días en el historial.
+ * @returns {Array<{fecha:string, tokens:number, exitos:number, fallos:number}>}
+ */
+function generarLineaTemporal({
+  rutaJsonl,
+  ventanaDias = VENTANA_DIAS_DEFAULT, // eslint-disable-line no-unused-vars
+  dias        = DIAS_LINEA_DEFAULT,
+} = {}) {
+  let eventos;
+  try {
+    eventos = leerJsonl(rutaJsonl);
+  } catch (_) {
+    eventos = [];
+  }
+
+  const ahora = Date.now();
+  const linea = [];
+
+  for (let i = dias - 1; i >= 0; i--) {
+    const inicioDia = ahora - (i + 1) * 24 * 3600 * 1000;
+    const finDia    = ahora - i * 24 * 3600 * 1000;
+    const fecha     = new Date(inicioDia).toISOString().slice(0, 10);
+
+    const del_dia = eventos.filter(e => {
+      const ms = aMs(e.timestamp ?? e.ts ?? e.inicio ?? e.created_at);
+      return !isNaN(ms) && ms >= inicioDia && ms < finDia;
+    });
+
+    const tokens = del_dia.reduce((s, e) => {
+      return s + (e.atributos?.tokens_totales ?? e.tokens ?? e.total_tokens ?? 0);
+    }, 0);
+
+    const exitos = del_dia.filter(e => {
+      const s = e.success ?? e.exito ?? e.atributos?.success;
+      return s === true || s === 1 || s === 'true';
+    }).length;
+
+    const fallos = del_dia.filter(e => {
+      const s = e.success ?? e.exito ?? e.atributos?.success;
+      return s === false || s === 0 || s === 'false';
+    }).length;
+
+    linea.push({ fecha, tokens, exitos, fallos });
+  }
+
+  return linea;
+}
+
+// ── Drift Score formalizado (Bhardwaj 2026, §3.12) ──────────────────────────
+//
+// Métrica continua D(t) ∈ [0, 1] que combina:
+//   - Componente compliance (lagging): 1 − C_soft(t), proporción de
+//     restricciones soft violadas en la ventana reciente.
+//   - Componente distribucional (leading): √JSD(P_obs ∥ P_ref), Jensen-
+//     Shannon divergence entre la distribución observada de acciones y la
+//     distribución de referencia. La √ comprime el rango y da más peso
+//     a desviaciones pequeñas detectables temprano.
+//
+// D(t) = w_c · (1 − C_soft) + w_d · √JSD
+//
+// Pesos por defecto w_c=0.7, w_d=0.3 reflejan que las violaciones son
+// señal más fuerte que la deriva distribucional. Configurables.
+//
+// Referencia: Bhardwaj V.P., "Agent Behavioral Contracts: Formal
+// Specification and Runtime Enforcement", arXiv:2602.22302v1, §3.12.
+//
+// Adaptación SWL: implementación zero-deps Node stdlib. Las distribuciones
+// son objetos plain {accion: probabilidad}.
+
+/**
+ * Calcula la divergencia Kullback-Leibler de p respecto a q sobre el soporte
+ * de p. Usa logaritmo natural. Convención: 0 · log(0/q) = 0.
+ *
+ * @param {object} p - Distribución como {clave: probabilidad}
+ * @param {object} q - Distribución como {clave: probabilidad}
+ * @returns {number} KL(p || q) en nats
+ */
+function divergenciaKL(p, q) {
+  let suma = 0;
+  for (const k of Object.keys(p)) {
+    const pi = p[k];
+    if (!pi || pi <= 0) continue;
+    const qi = q[k];
+    if (!qi || qi <= 0) {
+      // KL infinita si q asigna 0 a un evento que p considera posible.
+      // Convención práctica: usar smoothing mínimo en lugar de Infinity.
+      return Infinity;
+    }
+    suma += pi * Math.log(pi / qi);
+  }
+  return suma;
+}
+
+/**
+ * Jensen-Shannon divergence entre dos distribuciones discretas.
+ * Simétrica, acotada en [0, log(2)] con logaritmo natural.
+ * Aplicamos smoothing aditivo (Laplace) para evitar KL infinita cuando
+ * el soporte difiere.
+ *
+ * @param {object} pObs - Distribución observada (frecuencias o probs)
+ * @param {object} pRef - Distribución de referencia
+ * @returns {number} JSD normalizada en [0, 1]
+ */
+function divergenciaJS(pObs, pRef) {
+  const claves = new Set([...Object.keys(pObs || {}), ...Object.keys(pRef || {})]);
+  if (claves.size === 0) return 0;
+
+  // Normalizar a probabilidades + Laplace smoothing
+  const epsilon = 1e-9;
+  const p = {}, q = {};
+  let sumP = 0, sumQ = 0;
+  for (const k of claves) {
+    p[k] = (pObs?.[k] || 0) + epsilon;
+    q[k] = (pRef?.[k] || 0) + epsilon;
+    sumP += p[k];
+    sumQ += q[k];
+  }
+  for (const k of claves) {
+    p[k] /= sumP;
+    q[k] /= sumQ;
+  }
+
+  const m = {};
+  for (const k of claves) {
+    m[k] = 0.5 * (p[k] + q[k]);
+  }
+  const jsd = 0.5 * divergenciaKL(p, m) + 0.5 * divergenciaKL(q, m);
+  // Normalizar a [0,1] dividiendo por log(2)
+  return jsd / Math.log(2);
+}
+
+/**
+ * Calcula el Drift Score D(t) según Bhardwaj 2026, §3.12, adaptado a SWL.
+ *
+ * @param {object} opts
+ * @param {number} opts.compliance              - C_soft(t) ∈ [0, 1]; 1 = sin violaciones
+ * @param {object} [opts.accionesObservadas]    - {tool: count} en ventana reciente
+ * @param {object} [opts.accionesReferencia]    - {tool: count} en baseline
+ * @param {number} [opts.pesoCompliance=0.7]    - w_c
+ * @param {number} [opts.pesoDistribucion=0.3]  - w_d
+ * @returns {{
+ *   driftScore: number,
+ *   compliance_term: number,
+ *   distribucion_term: number,
+ *   jsd: number,
+ *   estado: 'ok' | 'warn' | 'critico'
+ * }}
+ */
+function calcularDriftScore({
+  compliance,
+  accionesObservadas,
+  accionesReferencia,
+  pesoCompliance = 0.7,
+  pesoDistribucion = 0.3,
+} = {}) {
+  const cClamp = typeof compliance === 'number'
+    ? Math.max(0, Math.min(1, compliance))
+    : 1;
+
+  const complianceTerm = 1 - cClamp;
+  const jsd = (accionesObservadas && accionesReferencia)
+    ? divergenciaJS(accionesObservadas, accionesReferencia)
+    : 0;
+  const distribucionTerm = Math.sqrt(Math.max(0, jsd));
+
+  const score = pesoCompliance * complianceTerm + pesoDistribucion * distribucionTerm;
+  const driftScore = Math.max(0, Math.min(1, score));
+
+  let estado = 'ok';
+  if (driftScore > 0.6) estado = 'critico';
+  else if (driftScore > 0.35) estado = 'warn';
+
+  return {
+    driftScore: Math.round(driftScore * 1000) / 1000,
+    compliance_term: Math.round(complianceTerm * 1000) / 1000,
+    distribucion_term: Math.round(distribucionTerm * 1000) / 1000,
+    jsd: Math.round(jsd * 1000) / 1000,
+    estado,
+  };
+}
+
+module.exports = {
+  detectarDrift,
+  generarLineaTemporal,
+  // Drift Score formalizado (Bhardwaj 2026 §3.12)
+  calcularDriftScore,
+  divergenciaJS,
+  // Exponer para tests
+  _leerJsonl:           leerJsonl,
+  _calcularMetricas:    calcularMetricas,
+  _estadoDrift:         estadoDrift,
+  _contarNudgesPrevios: contarNudgesPrevios,
+  _emitirNudgeDrift:    emitirNudgeDrift,
+  _divergenciaKL:       divergenciaKL,
+  METRICAS_DEFAULT,
+  REPAIR_LOOP_THRESHOLD,
+};

package/scripts/lib/estado.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Gestión de estado de instalación SWL.
+ * Persiste qué se instaló, dónde y cuándo para soporte de doctor/repair/uninstall.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const NOMBRE_ESTADO = '.swl-install-state.json';
+
+/**
+ * Crea un nuevo registro de estado de instalación
+ */
+function crearEstado(opciones) {
+  return {
+    version: 3,
+    sistema: 'swl-software-engineering-system',
+    versionSistema: opciones.versionSistema || '1.0.0',
+    target: opciones.target,
+    perfil: opciones.perfil,
+    rutaBase: opciones.rutaBase,
+    global: opciones.global || false,
+    componentesInstalados: [],
+    archivosInstalados: [],
+    componentesExternos: [],
+    hooksRegistrados: 0,
+    settingsModificado: false,
+    instaladoEn: new Date().toISOString(),
+    actualizadoEn: new Date().toISOString(),
+  };
+}
+
+/**
+ * Registra un archivo instalado en el estado
+ */
+function registrarArchivo(estado, archivo) {
+  estado.archivosInstalados.push({
+    origen: archivo.origen,
+    destino: archivo.destino,
+    tipo: archivo.tipo, // agente, habilidad, comando, regla, hook
+    checksum: archivo.checksum || null,
+    instaladoEn: new Date().toISOString(),
+  });
+  estado.actualizadoEn = new Date().toISOString();
+}
+
+/**
+ * Registra un componente instalado
+ */
+function registrarComponente(estado, componente) {
+  if (!estado.componentesInstalados.includes(componente)) {
+    estado.componentesInstalados.push(componente);
+    estado.actualizadoEn = new Date().toISOString();
+  }
+}
+
+/**
+ * Guarda el estado en disco
+ */
+function guardarEstado(estado, directorio) {
+  const rutaEstado = path.join(directorio, NOMBRE_ESTADO);
+  fs.writeFileSync(rutaEstado, JSON.stringify(estado, null, 2), 'utf-8');
+  return rutaEstado;
+}
+
+/**
+ * Carga el estado desde disco.
+ * Si detecta formato v2, migra automáticamente a v3.
+ */
+function cargarEstado(directorio) {
+  const rutaEstado = path.join(directorio, NOMBRE_ESTADO);
+  if (!fs.existsSync(rutaEstado)) {
+    return null;
+  }
+  try {
+    const estado = JSON.parse(fs.readFileSync(rutaEstado, 'utf-8'));
+    // Migración v2 → v3
+    if (estado.version === 2 || !estado.version) {
+      estado.version = 3;
+      if (!estado.componentesExternos) {
+        estado.componentesExternos = [];
+      }
+      // Persistir la migración
+      fs.writeFileSync(rutaEstado, JSON.stringify(estado, null, 2), 'utf-8');
+    }
+    return estado;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verifica integridad del estado contra archivos en disco
+ */
+function verificarIntegridad(estado) {
+  const problemas = [];
+
+  for (const archivo of estado.archivosInstalados) {
+    if (!fs.existsSync(archivo.destino)) {
+      problemas.push({
+        tipo: 'faltante',
+        archivo: archivo.destino,
+        mensaje: `Archivo instalado no encontrado: ${archivo.destino}`,
+      });
+    }
+  }
+
+  return {
+    integro: problemas.length === 0,
+    problemas,
+  };
+}
+
+module.exports = {
+  NOMBRE_ESTADO,
+  crearEstado,
+  registrarArchivo,
+  registrarComponente,
+  guardarEstado,
+  cargarEstado,
+  verificarIntegridad,
+};