@saulwade/swl-ses 1.4.0 → 1.4.2

package/habilidades/state-inconsistency-auditor-swl/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: state-inconsistency-auditor-swl
+description: >
+  Encuentra bugs donde una operación muta un fragmento de estado acoplado sin
+  actualizar su contraparte dependiente, causando corrupción silenciosa o fallos
+  en operaciones posteriores. Mapea sistemáticamente pares de estado acoplado,
+  todos sus paths de mutación, y los gaps donde un lado se actualiza sin el otro.
+  Language-agnostic (Python, TS, Go, Rust, Java, C#). Cargar cuando se sospeche
+  estado desincronizado: caché obsoleta, índices secundarios huérfanos, contadores
+  que no coinciden con la suma de sus partes, o permisos derivados que no reflejan
+  el estado de origen.
+---
+
+# Cuándo cargar
+
+- Sospechas que un caché, índice secundario, o contador agregado está desincronizado.
+- Una función actualiza la tabla principal pero no el índice derivado.
+- Hay paths de "emergencia" o "admin" que modifican estado sin pasar por el flujo normal.
+- Nemesis está corriendo su Pasada 2.
+
+# Cuándo NO cargar
+
+- Para búsqueda de vulnerabilidades conocidas (inyección SQL, XSS) — usar `revisor-seguridad-swl`.
+- Para revisión de lógica de función individual sin estado acoplado — usar `feynman-auditor-swl`.
+- Para módulos sin persistencia de estado (transformaciones funcionales puras, utilería).
+
+---
+
+# State Inconsistency Auditor
+
+Encuentra bugs donde una operación actualiza State A sin actualizar State B, cuando el invariante del sistema exige que ambos cambien juntos.
+
+Los patrones detallados de estado acoplado están en [recursos/coupled-state-patterns.md](recursos/coupled-state-patterns.md).
+
+---
+
+## El patrón abstracto
+
+Todo sistema mantiene **PARES DE ESTADO ACOPLADO**: dos o más valores de almacenamiento que deben mantener una relación (un invariante) entre sí. Cuando cualquier operación cambia un lado del par sin ajustar el otro, el invariante se rompe. Operaciones posteriores que leen ambos valores producen resultados incorrectos.
+
+---
+
+## Reglas del auditor
+
+```
+REGLA 0: MAPEAR ANTES DE CAZAR
+Nunca empezar a revisar funciones sin tener el mapa completo de
+dependencias de estado acoplado. No se puede encontrar una actualización
+faltante si no se sabe qué actualizaciones son necesarias.
+
+REGLA 1: TODOS LOS PATHS DE MUTACIÓN IMPORTAN
+Una variable de estado puede modificarse desde 5 funciones distintas.
+Las 5 deben actualizar el estado acoplado. Si 4 lo hacen y 1 no — ese es el bug.
+
+REGLA 2: LAS OPERACIONES PARCIALES SON LA FUENTE #1
+Las eliminaciones completas (eliminar todo) generalmente resetean todo el estado
+correctamente. Las operaciones parciales (reducir en X) frecuentemente olvidan
+reducir proporcionalmente el estado acoplado.
+
+REGLA 3: COMPARAR PATHS PARALELOS
+Si transferir() y eliminar() ambos reducen un balance, AMBOS deben actualizar
+el mismo conjunto de estado acoplado. Si uno lo hace y el otro no — hallazgo.
+
+REGLA 4: EL CÓDIGO DEFENSIVO ENMASCARA BUGS
+Código como `valor > minimo ? valor - minimo : 0` o `min(calculado, disponible)`
+oculta invariantes rotos silenciosamente. Son señales de alerta, no protecciones.
+
+REGLA 5: SOLO HALLAZGOS BASADOS EN EVIDENCIA
+Todo hallazgo debe incluir: el par acoplado, la operación que lo rompe,
+una secuencia de trigger concreta, y la consecuencia observable.
+```
+
+---
+
+## Proceso
+
+### Fase 1: Mapear pares de estado acoplado
+
+Para cada variable de almacenamiento, preguntar: **"¿Qué otros valores de almacenamiento deben cambiar cuando este cambia?"**
+
+Construir un mapa de dependencias. Ver patrones comunes en `recursos/coupled-state-patterns.md`.
+
+Salida de Fase 1: **Mapa de Dependencias de Estado Acoplado**.
+
+### Fase 2: Matriz de mutación
+
+Para cada variable identificada en Fase 1, listar TODAS las funciones y paths de código que la modifican. Incluir: escrituras directas, incrementos/decrementos, eliminaciones, mutaciones indirectas (llamadas internas), triggers externos (callbacks, hooks).
+
+Marcar con `???` toda entrada donde no se ha confirmado si la contraparte acoplada también se actualiza.
+
+Los `???` son los **objetivos primarios de auditoría**.
+
+### Fase 3: Cross-check — el corazón de la auditoría
+
+Para cada par (operación, variable de estado) de Fase 2:
+
+> "Esta operación modifica State A. ¿También actualiza todo el estado acoplado que depende de A?"
+
+Verificar específicamente:
+- Eliminación completa (A → 0): ¿se resetea/limpia todo el estado acoplado?
+- Eliminación parcial (A decrece): ¿se reduce proporcionalmente todo el estado acoplado?
+- Incremento (A crece): ¿se incrementa proporcionalmente todo el estado acoplado?
+- Transferencia (A se mueve entre entidades): ¿el estado acoplado se mueve también?
+- Eliminación de entrada de colección: ¿la entrada del par también se elimina?
+- Operación en lote: ¿el estado acoplado se actualiza por iteración o solo una vez?
+
+**Si algún path actualiza A sin actualizar su estado acoplado → HALLAZGO.**
+
+### Fase 4: Orden de operaciones dentro de funciones
+
+Muchas funciones realizan múltiples cambios de estado en secuencia. Rastrear el orden exacto y preguntar en cada paso: "¿Después de este paso, todos los pares acoplados siguen siendo consistentes?"
+
+Bugs de orden comunes:
+- Calcular resultado ANTES de actualizar el índice → resultado usa estado obsoleto
+- Leer caché DESPUÉS de modificar el origen → validación usa datos viejos
+- Emitir evento con valores viejos DESPUÉS del cambio de estado → sistemas externos se desincronizarán
+
+### Fase 5: Comparar paths paralelos
+
+Encontrar operaciones que logran resultados similares por paths distintos. Para cada grupo, comparar: ¿TODOS los paths actualizan el mismo estado acoplado?
+
+### Fase 6: Rastrear journeys multi-paso
+
+Simular secuencias donde un actor interactúa múltiples veces:
+
+1. Actor inicializa un recurso (estado inicializado)
+2. Tiempo pasa / estado externo evoluciona
+3. Actor hace modificación PARCIAL (el estado acoplado puede romperse aquí)
+4. Más tiempo pasa
+5. Actor hace otra operación que lee el estado acoplado
+
+En el paso 5: ¿el estado acoplado sigue siendo válido dado el cambio parcial del paso 3?
+
+### Fase 7: Patrones de enmascaramiento
+
+El código defensivo puede ocultar invariantes rotos. Ver patrones en `recursos/coupled-state-patterns.md`.
+
+Señal: si un ternario del tipo `a > b ? a - b : 0` está en un cálculo que involucra dos valores acoplados, preguntar: ¿por qué `a` podría ser menor que `b`? Si el invariante se mantuviera, no podría.
+
+---
+
+## Verificación (obligatoria para C/A/M)
+
+**Método A: Rastreo de código** — leer la función exacta, rastrear todas las llamadas internas, confirmar que no existe actualización oculta al estado acoplado.
+
+**Método B: Test de PoC** — escribir un test que ejecute la secuencia de trigger y afirme que el estado es inconsistente después de la operación.
+
+**Método C: Híbrido** — rastreo + PoC para hallazgos que abarcan múltiples módulos.
+
+**Falsos positivos frecuentes:**
+- Reconciliación oculta en un hook `_before_save` / `_after_update` / middleware.
+- Evaluación diferida intencional: el estado acoplado se reconcilia en la próxima lectura.
+- Asimetría de diseño documentada: los dos estados no son realmente acoplados como se asumió.
+
+---
+
+## Adaptación por lenguaje
+
+| Concepto | Python | TypeScript | Go | Rust | Java | C# |
+|---------|--------|------------|-----|------|------|-----|
+| Almacenamiento | atributos / BD | propiedades / BD | campos struct / BD | campos struct | campos clase | propiedades |
+| Colección clave-valor | `dict` / `HashMap` Redis | `Map` / objeto | `map[K]V` | `HashMap` | `Map<K,V>` | `Dictionary<K,V>` |
+| Eliminar entrada | `del d[k]` / `pop` | `delete obj[k]` | `delete(m, k)` | `map.remove(&k)` | `map.remove(k)` | `dict.Remove(k)` |
+| Hook post-mutación | `@receiver` / signal | middleware / hook | middleware | `impl Drop` / hook | `@PostUpdate` | event handler |
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/state-inconsistency-auditor-swl/recursos/coupled-state-patterns.md

@@ -0,0 +1,147 @@
+# Patrones de Estado Acoplado — Language-Agnostic
+
+9 patrones de estado acoplado frecuentes en sistemas Python, TypeScript, Go, Rust, Java y C#.
+
+---
+
+## Patrón 1: Balance ↔ Caché derivada
+
+**Descripción**: un valor base (balance de cuenta, stock de inventario, crédito disponible) tiene una caché calculada a partir de él (porcentaje disponible, categoría de riesgo, tier de cliente).
+
+**Invariante**: la caché debe reflejar el balance actual, no el del momento en que se calculó.
+
+**Paths de mutación riesgosos**: cualquier operación que modifica el balance directamente sin pasar por el flujo que actualiza la caché.
+
+**Trigger típico**: función de ajuste manual, importación masiva, o corrección administrativa que escribe el balance sin llamar al servicio que recalcula la caché.
+
+**Consecuencia**: decisiones que leen la caché (¿aplica descuento? ¿otorgar crédito?) usan datos obsoletos.
+
+---
+
+## Patrón 2: Registro principal ↔ Índice secundario
+
+**Descripción**: una tabla o colección tiene un índice secundario (índice invertido, tabla de búsqueda rápida, lista de IDs por categoría) que debe estar sincronizado con la tabla principal.
+
+**Invariante**: toda entrada en la tabla principal tiene exactamente una entrada correspondiente en el índice secundario (o exactamente ninguna, según el diseño).
+
+**Paths de mutación riesgosos**: delete de la tabla principal sin delete del índice; insert sin insert correspondiente; update que cambia la clave del índice sin actualizar el índice.
+
+**Trigger típico**: función de "purga" o "limpieza" que borra de la tabla principal pero olvida el índice. O migración que popula la tabla principal pero no regenera el índice.
+
+**Consecuencia**: búsquedas por índice devuelven resultados incorrectos (IDs que ya no existen, o registros que no aparecen en búsqueda aunque existan).
+
+---
+
+## Patrón 3: Contador agregado ↔ Suma de partes
+
+**Descripción**: un contador de totales (total de pedidos, total de puntos, total de items activos) debe ser igual a la suma de los contadores individuales.
+
+**Invariante**: `total == sum(individuales)` siempre.
+
+**Paths de mutación riesgosos**: operaciones que modifican un contador individual sin ajustar el total. Frecuente en operaciones de batch donde el total se actualiza una sola vez al final pero un error parcial deja los individuales en estado inconsistente.
+
+**Trigger típico**: transacción fallida a mitad que actualiza N de M elementos pero no revierte el total; o función que incrementa directamente el conteo individual sin notificar al agregador.
+
+**Consecuencia**: reportes y dashboards muestran cifras incorrectas; límites y cuotas se aplican con base en datos erróneos.
+
+---
+
+## Patrón 4: Sesión / Permiso derivado ↔ Recurso de origen
+
+**Descripción**: un objeto de sesión, token, o permiso derivado almacena un snapshot de los permisos o atributos del actor al momento de su creación. El actor puede cambiar después.
+
+**Invariante**: depende del diseño. Si los permisos se evalúan en tiempo de solicitud, el objeto derivado debe reflejar el estado actual del actor. Si se usan permisos fijados al momento de creación, el invariante es documentado explícitamente.
+
+**Paths de mutación riesgosos**: revocar permisos al actor sin invalidar sesiones activas; cambiar el rol del actor sin forzar re-autenticación; eliminar al actor sin expirar sus tokens.
+
+**Trigger típico**: función de "deshabilitar cuenta" que setea `is_active=False` en el usuario pero no invalida los tokens JWT o sesiones existentes.
+
+**Consecuencia**: actor deshabilitado sigue operando hasta que el token expira naturalmente.
+
+---
+
+## Patrón 5: Posición ↔ Factor de salud cacheado
+
+**Descripción**: un recurso con múltiples atributos (posición de deuda: monto + colateral + fecha + valor de mercado del colateral) tiene un factor calculado (ratio LTV, score de riesgo, estado de salud) que se cachea por rendimiento.
+
+**Invariante**: el factor cacheado debe recalcularse cada vez que cualquiera de sus inputs cambia.
+
+**Paths de mutación riesgosos**: actualizar cualquier input del cálculo sin invalidar o recalcular el factor cacheado.
+
+**Trigger típico**: función que actualiza el colateral sin llamar a `recalcular_factor()`. O función de ajuste de precio que modifica el valor de mercado sin propagar la invalidación de caché.
+
+**Consecuencia**: decisiones de riesgo (¿emitir alerta? ¿bloquear operación?) usan un factor obsoleto.
+
+---
+
+## Patrón 6: Replica / Proyección ↔ Origen CDC
+
+**Descripción**: un sistema mantiene una replica o proyección de datos de origen para acelerar lecturas (tabla denormalizada, proyección CQRS, replica de lectura, caché materializada). El origen puede cambiar vía CDC (Change Data Capture), eventos de dominio, o sincronización periódica.
+
+**Invariante**: la replica debe converger al estado del origen dentro de la ventana de latencia acordada.
+
+**Paths de mutación riesgosos**: escrituras directas al origen que no emiten el evento de dominio necesario para actualizar la replica; fallos en el consumer de eventos que quedan silenciosos; migraciones que modifican el origen sin reprocesar los eventos para actualizar la replica.
+
+**Trigger típico**: endpoint de "corrección de datos" que escribe directo a la BD origen sin publicar el evento de dominio correspondiente.
+
+**Consecuencia**: lecturas de la replica devuelven datos obsoletos indefinidamente.
+
+---
+
+## Patrón 7: Inventario total ↔ Items en almacén (por ubicación)
+
+**Descripción**: el inventario total de un SKU es la suma de los items en cada almacén o ubicación. Se mantiene desnormalizado por rendimiento.
+
+**Invariante**: `inventario_total[SKU] == sum(items_por_ubicacion[ubicacion][SKU] for ubicacion in todas)`
+
+**Paths de mutación riesgosos**: movimiento entre almacenes que decrementa una ubicación sin incrementar la otra; recepción en almacén sin incrementar el total; ajuste de inventario físico que corrige la ubicación sin propagar al total.
+
+**Trigger típico**: función de "ajuste de cierre" que actualiza el stock físico de un almacén sin pasar por la capa de negocio que mantiene el total sincronizado.
+
+**Consecuencia**: órdenes de compra se emiten sobre stock inexistente; o stock disponible no se vende por parecer agotado.
+
+---
+
+## Patrón 8: Estado de workflow ↔ Timestamps de auditoría
+
+**Descripción**: una entidad con workflow (pedido, solicitud, tarea) almacena su estado actual y los timestamps de cada transición. El timestamp de la última transición debe corresponder al estado actual.
+
+**Invariante**: `estado_actual` siempre tiene un timestamp asociado que refleja cuándo se alcanzó ese estado.
+
+**Paths de mutación riesgosos**: funciones que cambian el estado sin registrar el timestamp; o funciones que registran el timestamp sin actualizar el estado.
+
+**Trigger típico**: función de "forzar estado" en panel de administración que escribe `estado = 'COMPLETADO'` directamente sin pasar por la máquina de estados que registra `completado_en = now()`.
+
+**Consecuencia**: reportes de tiempo de ciclo son incorrectos; SLAs no se calculan bien; auditorías de cumplimiento fallan.
+
+---
+
+## Patrón 9: Configuración global ↔ Snapshot por instancia
+
+**Descripción**: hay una configuración global (tasa de impuesto, precio de tarifa, límite de política) y objetos que almacenan el valor que tenía la configuración en el momento de su creación (tasa de impuesto aplicada a esta factura, precio de tarifa al momento de la reserva).
+
+**Invariante**: el snapshot por instancia debe preservar el valor histórico, nunca actualizarse cuando cambia la configuración global. Pero si hay un bug en la creación, el snapshot puede haber capturado un valor incorrecto.
+
+**Paths de mutación riesgosos**: función que no captura el snapshot al crear la instancia y usa la configuración global en tiempo de lectura; o función de retroactiva que sobreescribe snapshots históricos con el valor actual de la configuración.
+
+**Trigger típico**: migración de datos que "normaliza" snapshots históricos al valor actual de la configuración global, destruyendo la trazabilidad.
+
+**Consecuencia**: recálculos retroactivos producen cifras incorrectas; auditorías de facturación no reproducen los valores originales.
+
+---
+
+## Patrones de enmascaramiento
+
+Código defensivo que oculta invariantes rotos en lugar de detectarlos:
+
+| Patrón | Código típico | Por qué es señal de alerta |
+|--------|--------------|---------------------------|
+| Ternario de clamp | `a > b ? a - b : 0` | Si el invariante se mantuviera, `a` nunca sería menor que `b` |
+| Try/catch vacío | `try { ... } catch {}` | El revert por estado roto se captura y se ignora |
+| Early exit en cero | `if value == 0: return` | Omite el cómputo cuando el estado roto produce cero |
+| Cap con min() | `min(calculado, disponible)` | El over-counting es el bug; `min()` solo evita el error visible |
+| Fallback a default | `valor = d.get(k, 0)` | Si la key debería existir pero fue eliminada sin limpiar el par, el default enmascara el dato faltante |
+
+Cuando se encuentra cualquiera de estos patrones en código que involucra dos valores acoplados, rastrear si el patrón existe porque el invariante ya estaba roto en algún path de mutación.
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->