@saulwade/swl-ses 1.5.1 → 1.6.0

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

@@ -1,147 +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) -->
+# 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) -->

package/habilidades/tdd-workflow/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: tdd-workflow
 description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.0.3"
+version: "1.0.4"
 evolved: true
-evolved-from: "1.0.2"
-evolved-at: "2026-05-15"
+evolved-from: "1.0.3"
+evolved-at: "2026-05-16"
 evolved-by: "aprender"
-evolved-note: "Gotcha process.cwd() cacheado al require() rompe tests con process.chdir(): fix con parámetro cwd opcional + fallback dinámico. Caso real scripts/derivar-feature-list.js v1.5.0."
+evolved-note: "v1.0.3: gotcha cwd cacheado al require(). v1.0.4: silenced tests por race en path único compartido + anti-patrón `if (X) assert(Y)` sin else. Origen PR #30 v1.5.2 (swl-ses)."
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -359,3 +359,120 @@ const r = enriquecerDesdeFases([], { cwd: sandbox });
 process.chdir(sandbox);
 const r2 = enriquecerDesdeFases([]);
 ```
+
+---
+
+## Gotcha: silenced tests por race condition sobre estado compartido
+
+### El anti-patrón
+
+```javascript
+// MAL — assertion condicional dentro de if que puede ser false por race
+const FLAG = path.join(os.tmpdir(), 'mi-app.json');
+
+test('flag sin contenido emite warning', () => {
+  borrarFlag();
+  const res = correrSubproceso();
+  if (fs.existsSync(FLAG)) {           // ← otro test paralelo creó el flag
+    assert.match(res.stdout, /WARN/);  // ← NUNCA se ejecuta si el if es false
+  }
+  // sin else → test PASA sin haber validado nada
+});
+
+// El test "verde" no significa "pasó" — significa "no falló ninguna assertion".
+// Si la assertion vive dentro de un `if (race)`, una race favorable la salta
+// y el test es vacío.
+```
+
+### Por qué pasa
+
+`node:test` paraleliza **archivos** `.test.js` por default (no tests dentro
+del mismo archivo). Si dos archivos tocan el mismo path único de filesystem
+(`/tmp/foo.json`, lockfiles, sockets), las operaciones se intercalan no
+deterministamente. Patrones típicos:
+
+- Archivo A: `borrarFlag()` → spawn subprocess → assert
+- Archivo B: spawn subprocess → `crearFlag()` durante A → assert de A condicionado falla
+
+### Patrones correctos
+
+**Patrón 1 — Aislamiento por path único** (recomendado):
+
+```javascript
+const env = { ...process.env };
+
+// Path único por test usando mkdtempSync — sin contención
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mi-app-test-'));
+env.MI_APP_FLAG_PATH = path.join(dir, 'flag.json');
+
+const res = spawnSync('node', [BIN], { env, ... });
+
+// Ahora el assert es incondicional — el path es del test, no compartido
+assert.match(res.stdout, /WARN/);
+```
+
+Requiere que el SUT (System Under Test) honre una env var para override
+del path. Si no la honra, agregar el override es parte del fix.
+
+**Patrón 2 — Serialización forzada** (cuando el path es hardcoded):
+
+```bash
+# Forzar --test-concurrency=1 en la suite completa
+node --test --test-concurrency=1 tests/
+```
+
+Tradeoff: tests más lentos pero deterministas. Aceptable si el aislamiento
+no es factible (legacy code).
+
+**Patrón 3 — assertions incondicionales** con setup determinista:
+
+```javascript
+// MAL
+if (fs.existsSync(FLAG)) assert.match(...)
+
+// BIEN — setup garantiza la precondición, assertion no se salta
+escribirFlag({ ... });
+assert.ok(fs.existsSync(FLAG), 'precondición del test');  // ← assertion sobre el setup
+const res = correrSubproceso();
+assert.match(res.stdout, /WARN/);  // ← assertion incondicional sobre el resultado
+```
+
+### Anti-patrón: `if (X) assert(Y)` sin `else`
+
+```javascript
+// MAL — un test que pasa silenciosamente cuando X es false
+test('hace algo', () => {
+  const algo = obtenerAlgo();
+  if (algo) {                       // ← race u otra fuente de no-determinismo
+    assert.equal(algo.valor, 42);
+  }
+  // sin else → veredicto "pass" sin haber validado nada
+});
+
+// BIEN — el setup garantiza la precondición o el test falla explícito
+test('hace algo', () => {
+  const algo = obtenerAlgo();
+  assert.ok(algo, 'precondición: obtenerAlgo debe devolver valor');
+  assert.equal(algo.valor, 42);
+});
+```
+
+**Regla**: una assertion dentro de un `if` sin `else` es **un test que
+puede pasar sin validar nada**. Estos "silenced tests" son la peor clase
+de falsa cobertura: el reporter dice "pass" y nadie revisa el código
+hasta que un bug llega a producción.
+
+### Detección
+
+- Buscar `if (` dentro de cuerpos de `test(...)`/`it(...)` sin `else { fail() }`
+  o `else { assert(...) }` correspondiente.
+- Si el cuerpo del `if` contiene `assert.*`, considerarlo silenced test
+  hasta que se demuestre que el `if` no puede ser false en ningún escenario.
+
+### Origen
+
+Detectado en sesión 2026-05-16 del proyecto swl-ses (PR #30): tests del
+flag `swl-ses-update-check.json` compartido entre dos archivos `.test.js`
+paralelos. El test "sin flag → debe advertir" pasaba en CI cuando otro
+archivo creaba el flag, sin ejecutar ninguna assertion. Fix: env var
+`SWL_UPDATE_FLAG_PATH` para aislamiento + assertions incondicionales.