@saulwade/swl-ses 1.3.8 → 1.4.0

package/scripts/lib/scoring-instintos.js

@@ -1,277 +1,277 @@
-'use strict';
-
-/**
- * scoring-instintos.js
- *
- * Sistema de decay exponencial + maturity transitions para instintos.
- *
- * Patrón adaptado de ACE (Agentic Context Engineering) en
- * `temp/cass_memory_system-main/src/scoring.ts`. Diferencias:
- *   - Funciones puras zero-deps (Node stdlib only).
- *   - Backward compatible: instintos sin los campos nuevos siguen siendo válidos.
- *   - No persiste — el caller decide cuándo escribir el resultado.
- *
- * Modelo:
- *   - `confidence` original es estática (asignada al crear).
- *   - `effective_confidence` se calcula dinámicamente:
- *       confidence × decay_factor − harmful_penalty
- *   - `decay_factor` = 2^(-days_since_validated / half_life_days) (default 90d).
- *   - `harmful_penalty` = HARMFUL_PENALTY_WEIGHT × harmful_ratio.
- *   - `maturity` se deriva de effective_confidence + evidence_count + harmful_ratio.
- *   - `shouldAutoDeprecate` cuando harmful_ratio > HARMFUL_RATIO_THRESHOLD
- *     con al menos MIN_FEEDBACK_FOR_DEPRECATION eventos.
- *
- * Campos NUEVOS opcionales en instintos (todos con defaults seguros):
- *   - decay_half_life_days  (default: 90)
- *   - helpful_count         (default: 0)
- *   - harmful_count         (default: 0)
- *   - last_validated_at     (default: last_validated, o created_at)
- *
- * @module scripts/lib/scoring-instintos
- */
-
-// ── constantes ────────────────────────────────────────────────────────────────
-
-const HALF_LIFE_DEFAULT_DAYS       = 90;
-const HARMFUL_RATIO_THRESHOLD      = 0.3;
-const MIN_FEEDBACK_FOR_DEPRECATION = 3;
-const HARMFUL_PENALTY_WEIGHT       = 0.5;
-const PROVEN_CONFIDENCE_THRESHOLD  = 0.7;
-const ESTABLISHED_THRESHOLD        = 0.5;
-const PROVEN_EVIDENCE_THRESHOLD    = 3;
-// Modelo de reforzamiento por feedback positivo (estilo agentmemory/lessons.ts).
-// Cada feedback positivo cierra un (1 - REINFORCEMENT_DECAY) = 10% del gap
-// entre la confianza actual y 1.0 — diminishing returns naturales.
-const REINFORCEMENT_DECAY          = 0.9;
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-/**
- * Días enteros entre dos fechas YYYY-MM-DD (o Date).
- * Tolerante a formato inválido: devuelve 0 si no parsea.
- */
-function daysBetween(d1, d2) {
-  const t1 = d1 instanceof Date ? d1.getTime() : Date.parse(String(d1));
-  const t2 = d2 instanceof Date ? d2.getTime() : Date.parse(String(d2));
-  if (Number.isNaN(t1) || Number.isNaN(t2)) return 0;
-  const diffMs = Math.abs(t2 - t1);
-  return Math.floor(diffMs / (24 * 3600 * 1000));
-}
-
-function clamp(n, min, max) {
-  if (Number.isNaN(n)) return min;
-  return Math.max(min, Math.min(max, n));
-}
-
-function getValidatedDate(instinto) {
-  return instinto.last_validated_at
-      || instinto.last_validated
-      || instinto.created_at
-      || null;
-}
-
-// ── funciones puras de scoring ────────────────────────────────────────────────
-
-/**
- * Factor de decay exponencial.
- *
- * decay(0)      = 1.0
- * decay(half)   = 0.5
- * decay(2×half) = 0.25
- *
- * @param {number} daysSinceValidated
- * @param {number} [halfLifeDays=90]
- * @returns {number} factor en [0, 1]
- */
-function decayFactor(daysSinceValidated, halfLifeDays = HALF_LIFE_DEFAULT_DAYS) {
-  if (daysSinceValidated <= 0) return 1.0;
-  if (halfLifeDays <= 0) return 1.0;
-  return Math.pow(2, -daysSinceValidated / halfLifeDays);
-}
-
-/**
- * Ratio de feedback dañino sobre el total de feedback recibido.
- * Devuelve 0 si no hay feedback.
- */
-function harmfulRatio(instinto) {
-  const helpful = instinto.helpful_count || 0;
-  const harmful = instinto.harmful_count || 0;
-  const total = helpful + harmful;
-  if (total === 0) return 0;
-  return harmful / total;
-}
-
-/**
- * Confianza reforzada por feedback positivo acumulado.
- *
- * Aplica un modelo de diminishing returns inspirado en `lessons.ts` de
- * agentmemory: cada feedback positivo cierra una fracción del gap entre la
- * confianza actual y 1.0. Aplicado N veces sobre la confianza base:
- *
- *     c_N = 1 - REINFORCEMENT_DECAY^N · (1 - c_0)
- *
- * Con `REINFORCEMENT_DECAY = 0.9`:
- *   - 1 feedback: c_0=0.5 → 0.55
- *   - 5 feedback: c_0=0.5 → 0.705
- *   - 10 feedback: c_0=0.5 → 0.826
- *   - 50 feedback: c_0=0.5 → 0.997
- *
- * Si no hay `helpful_count` (o es 0), devuelve la confianza base sin tocar.
- * Backward compatible: instintos sin el campo siguen comportándose igual.
- *
- * No persiste el resultado — se computa on-demand desde `helpful_count`. Eso
- * preserva el invariante "confidence original es estática".
- */
-function reinforcedConfidence(instinto) {
-  const baseConfidence = clamp(instinto.confidence || 0, 0, 1);
-  const helpful = instinto.helpful_count || 0;
-  if (helpful <= 0) return baseConfidence;
-  return 1 - Math.pow(REINFORCEMENT_DECAY, helpful) * (1 - baseConfidence);
-}
-
-/**
- * Confianza efectiva considerando reforzamiento, decay temporal y feedback
- * negativo.
- *
- *   effective = reinforced × decay − harmful_penalty
- *
- * @param {object} instinto
- * @param {string|Date} [currentDate=now] — fecha de referencia
- * @returns {number} en [0, 1]
- */
-function effectiveConfidence(instinto, currentDate) {
-  const now = currentDate || new Date();
-  const validatedAt = getValidatedDate(instinto);
-  const halfLife = instinto.decay_half_life_days || HALF_LIFE_DEFAULT_DAYS;
-
-  const days = validatedAt ? daysBetween(validatedAt, now) : 0;
-  const decay = decayFactor(days, halfLife);
-  const reinforced = reinforcedConfidence(instinto);
-  const penalty = HARMFUL_PENALTY_WEIGHT * harmfulRatio(instinto);
-
-  return clamp(reinforced * decay - penalty, 0, 1);
-}
-
-/**
- * Si el feedback negativo supera el umbral, recomendar auto-deprecación.
- * Requiere al menos MIN_FEEDBACK_FOR_DEPRECATION eventos para evitar
- * sobre-reaccionar a un solo voto.
- */
-function shouldAutoDeprecate(instinto) {
-  const helpful = instinto.helpful_count || 0;
-  const harmful = instinto.harmful_count || 0;
-  const total = helpful + harmful;
-  if (total < MIN_FEEDBACK_FOR_DEPRECATION) return false;
-  return harmfulRatio(instinto) > HARMFUL_RATIO_THRESHOLD;
-}
-
-/**
- * Estado de maduración derivado de effective_confidence + evidencia + feedback.
- *
- * Estados:
- *   - candidate    : effective < 0.5 (recién aprendido o decaído)
- *   - established  : 0.5 ≤ effective < 0.7
- *   - proven       : effective ≥ 0.7 AND evidence_count ≥ 3
- *   - deprecated   : shouldAutoDeprecate, status === 'archived', o
- *                    status === 'degraded' con contradictions ≥ 3
- */
-function maturityState(instinto, currentDate) {
-  if (instinto.status === 'archived') return 'deprecated';
-  if (shouldAutoDeprecate(instinto)) return 'deprecated';
-  if (instinto.status === 'degraded' && (instinto.contradictions || 0) >= 3) {
-    return 'deprecated';
-  }
-
-  const eff = effectiveConfidence(instinto, currentDate);
-  const evidence = instinto.evidence_count || 0;
-
-  if (eff >= PROVEN_CONFIDENCE_THRESHOLD && evidence >= PROVEN_EVIDENCE_THRESHOLD) {
-    return 'proven';
-  }
-  if (eff >= ESTABLISHED_THRESHOLD) return 'established';
-  return 'candidate';
-}
-
-/**
- * Aplicar feedback al instinto (pure: devuelve copia).
- * type: 'helpful' | 'harmful'
- *
- * Refresca last_validated_at — un feedback es una validación implícita.
- */
-function applyFeedback(instinto, type, currentDate) {
-  if (type !== 'helpful' && type !== 'harmful') {
-    throw new Error(`Tipo de feedback inválido: ${type}`);
-  }
-  const now = (currentDate instanceof Date)
-    ? currentDate.toISOString().slice(0, 10)
-    : (currentDate || new Date().toISOString().slice(0, 10));
-
-  const next = { ...instinto };
-  if (type === 'helpful') next.helpful_count = (next.helpful_count || 0) + 1;
-  else next.harmful_count = (next.harmful_count || 0) + 1;
-  next.last_validated_at = now;
-  return next;
-}
-
-/**
- * Recomputa status legacy + maturity como vista unificada.
- * Pure: devuelve un objeto enriquecido sin mutar el original.
- *
- * Si shouldAutoDeprecate, propone status='degraded' (no archive — el archive
- * es decisión humana). El caller decide si persistir el cambio.
- */
-function recomputeStatus(instinto, currentDate) {
-  const maturity = maturityState(instinto, currentDate);
-  const effective = effectiveConfidence(instinto, currentDate);
-  const proposed = { ...instinto, maturity, effective_confidence: Math.round(effective * 1000) / 1000 };
-
-  if (shouldAutoDeprecate(instinto) && instinto.status !== 'archived') {
-    proposed.status_proposed = 'degraded';
-    proposed.deprecation_reason = `harmful_ratio=${harmfulRatio(instinto).toFixed(2)} con ${(instinto.helpful_count||0)+(instinto.harmful_count||0)} eventos`;
-  }
-
-  return proposed;
-}
-
-/**
- * Adjuntar source tracing a un instinto (pure: devuelve copia).
- * Mantiene unicidad y orden de inserción.
- */
-function addSource(instinto, { sessionId, agentName } = {}) {
-  const next = { ...instinto };
-  if (sessionId) {
-    const s = new Set(next.source_sessions || []);
-    s.add(sessionId);
-    next.source_sessions = [...s];
-  }
-  if (agentName) {
-    const a = new Set(next.source_agents || []);
-    a.add(agentName);
-    next.source_agents = [...a];
-  }
-  return next;
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  daysBetween,
-  decayFactor,
-  harmfulRatio,
-  reinforcedConfidence,
-  effectiveConfidence,
-  shouldAutoDeprecate,
-  maturityState,
-  applyFeedback,
-  recomputeStatus,
-  addSource,
-  // constantes exportadas para tests y configuración
-  HALF_LIFE_DEFAULT_DAYS,
-  HARMFUL_RATIO_THRESHOLD,
-  MIN_FEEDBACK_FOR_DEPRECATION,
-  HARMFUL_PENALTY_WEIGHT,
-  PROVEN_CONFIDENCE_THRESHOLD,
-  ESTABLISHED_THRESHOLD,
-  PROVEN_EVIDENCE_THRESHOLD,
-  REINFORCEMENT_DECAY,
-};
+'use strict';
+
+/**
+ * scoring-instintos.js
+ *
+ * Sistema de decay exponencial + maturity transitions para instintos.
+ *
+ * Patrón adaptado de ACE (Agentic Context Engineering) en
+ * `temp/cass_memory_system-main/src/scoring.ts`. Diferencias:
+ *   - Funciones puras zero-deps (Node stdlib only).
+ *   - Backward compatible: instintos sin los campos nuevos siguen siendo válidos.
+ *   - No persiste — el caller decide cuándo escribir el resultado.
+ *
+ * Modelo:
+ *   - `confidence` original es estática (asignada al crear).
+ *   - `effective_confidence` se calcula dinámicamente:
+ *       confidence × decay_factor − harmful_penalty
+ *   - `decay_factor` = 2^(-days_since_validated / half_life_days) (default 90d).
+ *   - `harmful_penalty` = HARMFUL_PENALTY_WEIGHT × harmful_ratio.
+ *   - `maturity` se deriva de effective_confidence + evidence_count + harmful_ratio.
+ *   - `shouldAutoDeprecate` cuando harmful_ratio > HARMFUL_RATIO_THRESHOLD
+ *     con al menos MIN_FEEDBACK_FOR_DEPRECATION eventos.
+ *
+ * Campos NUEVOS opcionales en instintos (todos con defaults seguros):
+ *   - decay_half_life_days  (default: 90)
+ *   - helpful_count         (default: 0)
+ *   - harmful_count         (default: 0)
+ *   - last_validated_at     (default: last_validated, o created_at)
+ *
+ * @module scripts/lib/scoring-instintos
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+const HALF_LIFE_DEFAULT_DAYS       = 90;
+const HARMFUL_RATIO_THRESHOLD      = 0.3;
+const MIN_FEEDBACK_FOR_DEPRECATION = 3;
+const HARMFUL_PENALTY_WEIGHT       = 0.5;
+const PROVEN_CONFIDENCE_THRESHOLD  = 0.7;
+const ESTABLISHED_THRESHOLD        = 0.5;
+const PROVEN_EVIDENCE_THRESHOLD    = 3;
+// Modelo de reforzamiento por feedback positivo (estilo agentmemory/lessons.ts).
+// Cada feedback positivo cierra un (1 - REINFORCEMENT_DECAY) = 10% del gap
+// entre la confianza actual y 1.0 — diminishing returns naturales.
+const REINFORCEMENT_DECAY          = 0.9;
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Días enteros entre dos fechas YYYY-MM-DD (o Date).
+ * Tolerante a formato inválido: devuelve 0 si no parsea.
+ */
+function daysBetween(d1, d2) {
+  const t1 = d1 instanceof Date ? d1.getTime() : Date.parse(String(d1));
+  const t2 = d2 instanceof Date ? d2.getTime() : Date.parse(String(d2));
+  if (Number.isNaN(t1) || Number.isNaN(t2)) return 0;
+  const diffMs = Math.abs(t2 - t1);
+  return Math.floor(diffMs / (24 * 3600 * 1000));
+}
+
+function clamp(n, min, max) {
+  if (Number.isNaN(n)) return min;
+  return Math.max(min, Math.min(max, n));
+}
+
+function getValidatedDate(instinto) {
+  return instinto.last_validated_at
+      || instinto.last_validated
+      || instinto.created_at
+      || null;
+}
+
+// ── funciones puras de scoring ────────────────────────────────────────────────
+
+/**
+ * Factor de decay exponencial.
+ *
+ * decay(0)      = 1.0
+ * decay(half)   = 0.5
+ * decay(2×half) = 0.25
+ *
+ * @param {number} daysSinceValidated
+ * @param {number} [halfLifeDays=90]
+ * @returns {number} factor en [0, 1]
+ */
+function decayFactor(daysSinceValidated, halfLifeDays = HALF_LIFE_DEFAULT_DAYS) {
+  if (daysSinceValidated <= 0) return 1.0;
+  if (halfLifeDays <= 0) return 1.0;
+  return Math.pow(2, -daysSinceValidated / halfLifeDays);
+}
+
+/**
+ * Ratio de feedback dañino sobre el total de feedback recibido.
+ * Devuelve 0 si no hay feedback.
+ */
+function harmfulRatio(instinto) {
+  const helpful = instinto.helpful_count || 0;
+  const harmful = instinto.harmful_count || 0;
+  const total = helpful + harmful;
+  if (total === 0) return 0;
+  return harmful / total;
+}
+
+/**
+ * Confianza reforzada por feedback positivo acumulado.
+ *
+ * Aplica un modelo de diminishing returns inspirado en `lessons.ts` de
+ * agentmemory: cada feedback positivo cierra una fracción del gap entre la
+ * confianza actual y 1.0. Aplicado N veces sobre la confianza base:
+ *
+ *     c_N = 1 - REINFORCEMENT_DECAY^N · (1 - c_0)
+ *
+ * Con `REINFORCEMENT_DECAY = 0.9`:
+ *   - 1 feedback: c_0=0.5 → 0.55
+ *   - 5 feedback: c_0=0.5 → 0.705
+ *   - 10 feedback: c_0=0.5 → 0.826
+ *   - 50 feedback: c_0=0.5 → 0.997
+ *
+ * Si no hay `helpful_count` (o es 0), devuelve la confianza base sin tocar.
+ * Backward compatible: instintos sin el campo siguen comportándose igual.
+ *
+ * No persiste el resultado — se computa on-demand desde `helpful_count`. Eso
+ * preserva el invariante "confidence original es estática".
+ */
+function reinforcedConfidence(instinto) {
+  const baseConfidence = clamp(instinto.confidence || 0, 0, 1);
+  const helpful = instinto.helpful_count || 0;
+  if (helpful <= 0) return baseConfidence;
+  return 1 - Math.pow(REINFORCEMENT_DECAY, helpful) * (1 - baseConfidence);
+}
+
+/**
+ * Confianza efectiva considerando reforzamiento, decay temporal y feedback
+ * negativo.
+ *
+ *   effective = reinforced × decay − harmful_penalty
+ *
+ * @param {object} instinto
+ * @param {string|Date} [currentDate=now] — fecha de referencia
+ * @returns {number} en [0, 1]
+ */
+function effectiveConfidence(instinto, currentDate) {
+  const now = currentDate || new Date();
+  const validatedAt = getValidatedDate(instinto);
+  const halfLife = instinto.decay_half_life_days || HALF_LIFE_DEFAULT_DAYS;
+
+  const days = validatedAt ? daysBetween(validatedAt, now) : 0;
+  const decay = decayFactor(days, halfLife);
+  const reinforced = reinforcedConfidence(instinto);
+  const penalty = HARMFUL_PENALTY_WEIGHT * harmfulRatio(instinto);
+
+  return clamp(reinforced * decay - penalty, 0, 1);
+}
+
+/**
+ * Si el feedback negativo supera el umbral, recomendar auto-deprecación.
+ * Requiere al menos MIN_FEEDBACK_FOR_DEPRECATION eventos para evitar
+ * sobre-reaccionar a un solo voto.
+ */
+function shouldAutoDeprecate(instinto) {
+  const helpful = instinto.helpful_count || 0;
+  const harmful = instinto.harmful_count || 0;
+  const total = helpful + harmful;
+  if (total < MIN_FEEDBACK_FOR_DEPRECATION) return false;
+  return harmfulRatio(instinto) > HARMFUL_RATIO_THRESHOLD;
+}
+
+/**
+ * Estado de maduración derivado de effective_confidence + evidencia + feedback.
+ *
+ * Estados:
+ *   - candidate    : effective < 0.5 (recién aprendido o decaído)
+ *   - established  : 0.5 ≤ effective < 0.7
+ *   - proven       : effective ≥ 0.7 AND evidence_count ≥ 3
+ *   - deprecated   : shouldAutoDeprecate, status === 'archived', o
+ *                    status === 'degraded' con contradictions ≥ 3
+ */
+function maturityState(instinto, currentDate) {
+  if (instinto.status === 'archived') return 'deprecated';
+  if (shouldAutoDeprecate(instinto)) return 'deprecated';
+  if (instinto.status === 'degraded' && (instinto.contradictions || 0) >= 3) {
+    return 'deprecated';
+  }
+
+  const eff = effectiveConfidence(instinto, currentDate);
+  const evidence = instinto.evidence_count || 0;
+
+  if (eff >= PROVEN_CONFIDENCE_THRESHOLD && evidence >= PROVEN_EVIDENCE_THRESHOLD) {
+    return 'proven';
+  }
+  if (eff >= ESTABLISHED_THRESHOLD) return 'established';
+  return 'candidate';
+}
+
+/**
+ * Aplicar feedback al instinto (pure: devuelve copia).
+ * type: 'helpful' | 'harmful'
+ *
+ * Refresca last_validated_at — un feedback es una validación implícita.
+ */
+function applyFeedback(instinto, type, currentDate) {
+  if (type !== 'helpful' && type !== 'harmful') {
+    throw new Error(`Tipo de feedback inválido: ${type}`);
+  }
+  const now = (currentDate instanceof Date)
+    ? currentDate.toISOString().slice(0, 10)
+    : (currentDate || new Date().toISOString().slice(0, 10));
+
+  const next = { ...instinto };
+  if (type === 'helpful') next.helpful_count = (next.helpful_count || 0) + 1;
+  else next.harmful_count = (next.harmful_count || 0) + 1;
+  next.last_validated_at = now;
+  return next;
+}
+
+/**
+ * Recomputa status legacy + maturity como vista unificada.
+ * Pure: devuelve un objeto enriquecido sin mutar el original.
+ *
+ * Si shouldAutoDeprecate, propone status='degraded' (no archive — el archive
+ * es decisión humana). El caller decide si persistir el cambio.
+ */
+function recomputeStatus(instinto, currentDate) {
+  const maturity = maturityState(instinto, currentDate);
+  const effective = effectiveConfidence(instinto, currentDate);
+  const proposed = { ...instinto, maturity, effective_confidence: Math.round(effective * 1000) / 1000 };
+
+  if (shouldAutoDeprecate(instinto) && instinto.status !== 'archived') {
+    proposed.status_proposed = 'degraded';
+    proposed.deprecation_reason = `harmful_ratio=${harmfulRatio(instinto).toFixed(2)} con ${(instinto.helpful_count||0)+(instinto.harmful_count||0)} eventos`;
+  }
+
+  return proposed;
+}
+
+/**
+ * Adjuntar source tracing a un instinto (pure: devuelve copia).
+ * Mantiene unicidad y orden de inserción.
+ */
+function addSource(instinto, { sessionId, agentName } = {}) {
+  const next = { ...instinto };
+  if (sessionId) {
+    const s = new Set(next.source_sessions || []);
+    s.add(sessionId);
+    next.source_sessions = [...s];
+  }
+  if (agentName) {
+    const a = new Set(next.source_agents || []);
+    a.add(agentName);
+    next.source_agents = [...a];
+  }
+  return next;
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  daysBetween,
+  decayFactor,
+  harmfulRatio,
+  reinforcedConfidence,
+  effectiveConfidence,
+  shouldAutoDeprecate,
+  maturityState,
+  applyFeedback,
+  recomputeStatus,
+  addSource,
+  // constantes exportadas para tests y configuración
+  HALF_LIFE_DEFAULT_DAYS,
+  HARMFUL_RATIO_THRESHOLD,
+  MIN_FEEDBACK_FOR_DEPRECATION,
+  HARMFUL_PENALTY_WEIGHT,
+  PROVEN_CONFIDENCE_THRESHOLD,
+  ESTABLISHED_THRESHOLD,
+  PROVEN_EVIDENCE_THRESHOLD,
+  REINFORCEMENT_DECAY,
+};