# EVENTS_SYSTEM.md — Sistema de Eventos del Organismo 4GatosCoin

El **Sistema de Eventos** es el sistema nervioso del organismo 4GatosCoin.  
Es la capa que detecta, procesa y distribuye todos los eventos internos: gestos, energía, rituales, ciclos, temporadas, semillas, territorio, narrativa y anomalías.

Este documento describe cómo funciona, cómo se estructura, cómo se propagan los eventos y cómo deben implementarse.

---

# 1. ¿Qué es un Evento?

Un evento es:

- un cambio en el organismo  
- una acción del usuario  
- una transición de estado  
- un disparador de narrativa  
- un impacto en energía, territorio o avatar  

Los eventos permiten que el organismo **reaccione**, **evolucione** y **se sincronice**.

---

# 2. Componentes Técnicos

### 2.1. Modelo
Los eventos se registran en:

```
models/Log.ts
```

### 2.2. Bus de eventos (futuro)
```
lib/events/bus.ts
```

### 2.3. Tipos de eventos
Definidos en:

```
types/Event.ts
```

### 2.4. Panel DevWeb3
Ubicación:

```
app/devweb3/eventos/
```

Funciones:

- ver eventos recientes  
- filtrar por tipo  
- ver impacto  
- activar eventos manualmente (solo dev)  

---

# 3. Tipos de Eventos

## 3.1. Eventos de Gesto
Generados por:

- `POST /api/gesture`

Ejemplo:

```json
{
  "type": "gesture",
  "gesture": "pulso_vocal",
  "wallet": "0xabc..."
}
```

---

## 3.2. Eventos de Puntos
Generados por:

- asignación de puntos  
- bonus  
- penalizaciones  

---

## 3.3. Eventos de Energía
Generados por:

- generación  
- consumo  
- rituales  
- ciclos  

---

## 3.4. Eventos de Semillas
Generados por:

- generación  
- rareza  
- distribución  

---

## 3.5. Eventos de Rituales
Generados por:

- activación  
- participación  
- impacto  

---

## 3.6. Eventos de Ciclos
Generados por:

- completar ciclo  
- alcanzar umbral  

---

## 3.7. Eventos de Temporadas
Generados por:

- inicio de temporada  
- transición  
- cierre  

---

## 3.8. Eventos de Territorio
Generados por:

- expansión  
- dominancia  
- zonas activas  

---

## 3.9. Eventos de Narrativa
Generados por:

- ecos  
- silencios  
- anomalías narrativas  

---

## 3.10. Eventos de Anomalía
Generados por:

- actividad inusual  
- ráfagas  
- errores rituales  
- patrones inesperados  

---

# 4. Flujo de un Evento

```
Evento → Clasificación → Procesamiento → Impacto → Registro → Propagación
```

### 4.1. Entrada
El sistema recibe:

- gestos  
- energía  
- memoria  
- avatar  
- territorio  
- ciclos  
- temporadas  
- rituales  
- semillas  
- anomalías  

### 4.2. Clasificación
El sistema determina el tipo de evento.

### 4.3. Procesamiento
El evento se envía a los órganos correspondientes.

### 4.4. Impacto
El evento puede afectar:

- energía  
- territorio  
- avatar  
- narrativa  
- memoria  
- ciclos  
- temporadas  

### 4.5. Registro
Se registra en logs.

### 4.6. Propagación
El evento puede generar nuevos eventos.

Ejemplo:

```
gesto → puntos → energía → latido → narrativa
```

---

# 5. Propagación de Eventos

El sistema permite propagación en cadena:

### 5.1. Propagación simple
```
gesto → puntos
```

### 5.2. Propagación múltiple
```
gesto → puntos → energía → latido
```

### 5.3. Propagación profunda
```
gesto → eco → memoria → narrativa → territorio → temporada
```

### 5.4. Propagación ritual
```
cláusula → ritual → energía → ciclo → temporada
```

---

# 6. Relación con Otros Órganos

### 6.1. Con Memoria
Los eventos alimentan la memoria viva.

### 6.2. Con Energía
Los eventos energéticos afectan latido y territorio.

### 6.3. Con Avatar
Los eventos personales afectan narrativa individual.

### 6.4. Con Territorio
Los eventos territoriales afectan zonas.

### 6.5. Con Temporadas
Los eventos pueden iniciar temporadas.

### 6.6. Con Rituales
Los rituales generan eventos masivos.

---

# 7. Ejemplo de Evento Completo

```json
{
  "type": "gesture",
  "wallet": "0xabc...",
  "gesture": "pulso_vocal",
  "timestamp": 1700000000,
  "propagation": [
    "points_added",
    "energy_generated",
    "heartbeat_increase",
    "narrative_echo"
  ]
}
```

---

# 8. Cómo Extender el Sistema de Eventos

1. Añadir tipos en:
   ```
   types/Event.ts
   ```
2. Añadir lógica en:
   ```
   lib/events/
   ```
3. Añadir UI en:
   ```
   app/devweb3/eventos/
   ```
4. Actualizar documentación si aplica.

---

# 9. Roadmap del Sistema de Eventos

- bus de eventos real  
- eventos combinatorios  
- eventos por avatar  
- eventos territoriales avanzados  
- eventos narrativos profundos  
- eventos visualizados en OTT  
- eventos por temporada  
- eventos rituales avanzados  

---

# 10. Licencia
Proyecto interno.  
Acceso restringido a desarrolladores autorizados.