---
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.
version: "1.0.0"
exclusiones:
  - "No cargar para bugs de lógica en función individual — usar feynman-auditor-swl."
  - "No cargar para auditoría de race conditions en código concurrente — eso requiere análisis específico de threading/async."
  - "No cargar para módulos sin estado mutable o sin pares de estado acoplado — el patrón no aplica."
  - "No cargar para revisión de estilo o legibilidad — usar revisor-codigo-swl."
---

# 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) -->
