# GLOBAL_STATE.md — Estado Global del Organismo 4GatosCoin

El **Estado Global** es la representación completa y unificada del organismo 4GatosCoin en un momento dado.  
Es la síntesis de todos los órganos: energía, territorio, memoria, avatar, ciclos, temporadas, rituales, semillas, puntos y latido.

Este documento describe cómo se estructura, cómo se actualiza, cómo se consulta y cómo debe implementarse.

---

# 1. ¿Qué es el Estado Global?

El Estado Global es:

- el **corazón técnico** del organismo  
- la **fuente de verdad** para todos los paneles  
- el **punto de sincronización** entre órganos  
- la **memoria viva** del estado actual  
- la **base** para visualización OTT  
- el **motor** de temporadas y ciclos  

Es el archivo que define cómo está el organismo **ahora mismo**.

---

# 2. Ubicación Técnica

El estado global se almacena en:

```
models/OrganismoGlobal.ts
```

Y se consulta desde:

```
GET /api/organismo-global
```

---

# 3. Estructura del Estado Global

Ejemplo completo:

```json
{
  "energia": 1200,
  "energiaPorZona": {
    "norte": 300,
    "sur": 250,
    "este": 320,
    "oeste": 330
  },
  "territorio": {
    "zonas": 4,
    "dominancia": {
      "norte": 12,
      "sur": 8,
      "este": 5,
      "oeste": 9
    }
  },
  "ciclos": 12,
  "temporada": 3,
  "heartbeat": 88,
  "memoria": {
    "ecos": 20,
    "rituales": 2,
    "silencios": 4,
    "anomalías": 1
  },
  "ritualesActivos": ["elgritoquecrea"],
  "puntosTotales": 4200,
  "semillasTotales": 88,
  "usuariosActivos": 42,
  "lastUpdate": 1700000000
}
```

---

# 4. Componentes del Estado Global

## 4.1. Energía
- energía total  
- energía por zona  
- energía por ciclo  
- energía por temporada  

## 4.2. Territorio
- zonas  
- dominancia  
- actividad local  
- expansión  

## 4.3. Ciclos
- ciclo actual  
- energía acumulada  
- umbrales  

## 4.4. Temporada
- temporada actual  
- reglas activas  
- ambiente  

## 4.5. Latido
- frecuencia  
- intensidad  
- variación  

## 4.6. Memoria
- ecos  
- rituales  
- silencios  
- anomalías  

## 4.7. Rituales
- rituales activos  
- rituales recientes  

## 4.8. Puntos
- puntos totales  
- puntos por usuario  

## 4.9. Semillas
- semillas totales  
- rarezas  
- distribución  

## 4.10. Usuarios
- usuarios activos  
- avatares sincronizados  

---

# 5. Flujo del Estado Global

```
Gestos → Puntos → Energía → Latido → Territorio → Ciclos → Temporadas → Memoria → Estado Global
```

El Estado Global se recalcula cada vez que:

- se ejecuta un gesto  
- se genera energía  
- se completa un ciclo  
- se activa un ritual  
- se inicia una temporada  
- se genera una semilla  
- se registra un evento de memoria  

---

# 6. Endpoints Relacionados

### 6.1. Obtener estado global
```
GET /api/organismo-global
```

### 6.2. Actualizar estado global (interno)
```
lib/organismo/updateGlobalState.ts
```

### 6.3. Panel DevWeb3
```
app/devweb3/organismo/
```

Funciones:

- ver estado global  
- ver evolución  
- ver logs asociados  
- activar modo debug  

---

# 7. Relación con Otros Órganos

### 7.1. Con OTT
OTT consume el estado global para visualización.

### 7.2. Con Temporadas
Las temporadas modifican reglas del estado global.

### 7.3. Con Ciclos
Los ciclos dependen de energía y territorio.

### 7.4. Con Avatar
El avatar se sincroniza con el estado global.

### 7.5. Con Memoria
La memoria profunda altera el estado global.

### 7.6. Con Rituales
Los rituales generan cambios masivos.

---

# 8. Ejemplo de Evento que Actualiza el Estado Global

```json
{
  "type": "gesture",
  "wallet": "0xabc...",
  "gesture": "pulso_vocal",
  "pointsAdded": 3,
  "energyGenerated": 3,
  "impact": "heartbeat_increase"
}
```

---

# 9. Cómo Extender el Estado Global

1. Añadir campos en:
   ```
   models/OrganismoGlobal.ts
   ```
2. Añadir lógica en:
   ```
   lib/organismo/updateGlobalState.ts
   ```
3. Añadir UI en:
   ```
   app/devweb3/organismo/
   ```
4. Actualizar documentación si aplica.

---

# 10. Roadmap del Estado Global

- estado global por zona  
- estado global por avatar  
- estado global ritual  
- estado global narrativo  
- estado global visualizado en OTT  
- estado global por temporada  

---

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