docs(v5): Complete system documentation
Comprehensive documentation for TZZR system v5 including: - 00_VISION: Glossary and foundational philosophy - 01_ARQUITECTURA: System overview and server specs - 02_MODELO_DATOS: Entity definitions and data planes (T0, MST, BCK) - 03_COMPONENTES: Agent docs (CLARA, MARGARET, FELDMAN, GRACE) - 04_SEGURIDAD: Threat model and secrets management - 05_OPERACIONES: Infrastructure and backup/recovery - 06_INTEGRACIONES: GPU services (RunPod status: blocked) - 99_ANEXOS: Repository inventory (24 repos) Key findings documented: - CRITICAL: UFW inactive on CORP/HST - CRITICAL: PostgreSQL 5432 exposed - CRITICAL: .env files with 644 permissions - RunPod workers not starting (code ready in R2) - Infisical designated as single source of secrets (D-001) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
ARCHITECT
390
03_COMPONENTES/agentes/feldman.md
Normal file
390
03_COMPONENTES/agentes/feldman.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# FELDMAN - Agente de Consolidación
|
||||
|
||||
**Versión:** 5.0
|
||||
**Fecha:** 2024-12-24
|
||||
|
||||
---
|
||||
|
||||
## Resumen
|
||||
|
||||
| Aspecto | Valor |
|
||||
|---------|-------|
|
||||
| Servidor | CORP (92.112.181.188) |
|
||||
| Puerto | 5054 |
|
||||
| Base de datos | corp |
|
||||
| Tablas | feldman_cola, feldman_bloques, feldman_validaciones |
|
||||
| Estado | Operativo |
|
||||
|
||||
---
|
||||
|
||||
## Rol en el Sistema
|
||||
|
||||
FELDMAN es el "notario" del sistema: valida y consolida datos en bloques inmutables.
|
||||
|
||||
```
|
||||
MASON (enriquecido)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ FELDMAN │
|
||||
│ │
|
||||
│ 1. Recibir en feldman_cola │
|
||||
│ 2. Validar reglas (M-001, M-002, M-003)│
|
||||
│ 3. Calcular hash_contenido │
|
||||
│ 4. Encadenar (hash_previo) │
|
||||
│ 5. Crear milestone o bloque │
|
||||
│ 6. Marcar como consolidado │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ milestones / bloques (inmutables) │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
SENTINEL (auditoría futura)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Validación
|
||||
|
||||
| Regla | Nombre | Descripción | Acción si falla |
|
||||
|-------|--------|-------------|-----------------|
|
||||
| M-001 | Hash único | h_bloque/h_milestone no existe previamente | Rechazar |
|
||||
| M-002 | Encadenamiento | hash_previo apunta a bloque existente | Rechazar |
|
||||
| M-003 | Integridad | hash_contenido = SHA-256(contenido) | Rechazar |
|
||||
|
||||
### Implementación
|
||||
|
||||
```python
|
||||
def validar_m001(h_bloque):
|
||||
"""M-001: Hash debe ser único."""
|
||||
existe = db.execute(
|
||||
"SELECT 1 FROM bloques WHERE h_bloque = %s",
|
||||
[h_bloque]
|
||||
).fetchone()
|
||||
return existe is None
|
||||
|
||||
def validar_m002(hash_previo, h_instancia):
|
||||
"""M-002: hash_previo debe existir (excepto génesis)."""
|
||||
if hash_previo is None:
|
||||
# Primer bloque de la instancia (génesis)
|
||||
existe = db.execute(
|
||||
"SELECT 1 FROM bloques WHERE h_instancia = %s",
|
||||
[h_instancia]
|
||||
).fetchone()
|
||||
return existe is None # OK si no hay bloques previos
|
||||
|
||||
existe = db.execute(
|
||||
"SELECT 1 FROM bloques WHERE h_bloque = %s",
|
||||
[hash_previo]
|
||||
).fetchone()
|
||||
return existe is not None
|
||||
|
||||
def validar_m003(hash_contenido, contenido):
|
||||
"""M-003: Hash debe coincidir con contenido."""
|
||||
import hashlib
|
||||
import json
|
||||
|
||||
contenido_serializado = json.dumps(contenido, sort_keys=True)
|
||||
hash_calculado = hashlib.sha256(contenido_serializado.encode()).hexdigest()
|
||||
|
||||
return hash_contenido == hash_calculado
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schema de Tablas
|
||||
|
||||
### feldman_cola
|
||||
|
||||
```sql
|
||||
CREATE TABLE feldman_cola (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
tipo VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque'
|
||||
h_entrada VARCHAR(64) NOT NULL, -- Referencia a origen
|
||||
h_instancia VARCHAR(64) NOT NULL,
|
||||
contenido JSONB NOT NULL,
|
||||
prioridad INTEGER DEFAULT 0,
|
||||
estado VARCHAR(20) DEFAULT 'pendiente',
|
||||
intentos INTEGER DEFAULT 0,
|
||||
ultimo_error TEXT,
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
processed_at TIMESTAMPTZ
|
||||
);
|
||||
|
||||
CREATE INDEX idx_feldman_cola_estado ON feldman_cola(estado);
|
||||
CREATE INDEX idx_feldman_cola_prioridad ON feldman_cola(prioridad DESC);
|
||||
```
|
||||
|
||||
### feldman_bloques (alias de bloques)
|
||||
|
||||
```sql
|
||||
-- Ver 02_MODELO_DATOS/planos.md para schema completo
|
||||
CREATE TABLE bloques (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
h_bloque VARCHAR(64) UNIQUE NOT NULL,
|
||||
h_instancia VARCHAR(64) NOT NULL,
|
||||
secuencia BIGINT NOT NULL,
|
||||
hash_previo VARCHAR(64),
|
||||
hash_contenido VARCHAR(64) NOT NULL,
|
||||
tipo_bloque VARCHAR(50) NOT NULL,
|
||||
contenido JSONB NOT NULL,
|
||||
-- ... campos adicionales
|
||||
UNIQUE (h_instancia, secuencia)
|
||||
);
|
||||
```
|
||||
|
||||
### feldman_validaciones
|
||||
|
||||
```sql
|
||||
CREATE TABLE feldman_validaciones (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
h_entrada VARCHAR(64) NOT NULL,
|
||||
tipo_destino VARCHAR(50) NOT NULL, -- 'milestone' o 'bloque'
|
||||
h_destino VARCHAR(64), -- h_milestone o h_bloque
|
||||
regla VARCHAR(50) NOT NULL, -- M-001, M-002, M-003
|
||||
resultado BOOLEAN NOT NULL,
|
||||
mensaje TEXT,
|
||||
validated_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_feldman_val_entrada ON feldman_validaciones(h_entrada);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Flujo de Consolidación
|
||||
|
||||
```
|
||||
1. Entrada en feldman_cola
|
||||
│
|
||||
▼
|
||||
2. FELDMAN procesa (poll cada N segundos)
|
||||
│
|
||||
├─► Validar M-001 (hash único)
|
||||
│ ├─ PASS → continuar
|
||||
│ └─ FAIL → registrar error, marcar 'rechazado'
|
||||
│
|
||||
├─► Validar M-002 (encadenamiento)
|
||||
│ ├─ PASS → continuar
|
||||
│ └─ FAIL → registrar error, marcar 'rechazado'
|
||||
│
|
||||
├─► Validar M-003 (integridad)
|
||||
│ ├─ PASS → continuar
|
||||
│ └─ FAIL → registrar error, marcar 'rechazado'
|
||||
│
|
||||
▼
|
||||
3. Todas las validaciones PASS
|
||||
│
|
||||
▼
|
||||
4. Obtener última secuencia de h_instancia
|
||||
│
|
||||
▼
|
||||
5. Calcular h_bloque/h_milestone
|
||||
│
|
||||
▼
|
||||
6. INSERT en bloques/milestones
|
||||
│
|
||||
▼
|
||||
7. Actualizar feldman_cola → 'consolidado'
|
||||
│
|
||||
▼
|
||||
8. Registrar en feldman_validaciones
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cálculo de Hashes
|
||||
|
||||
### h_bloque
|
||||
|
||||
```python
|
||||
def calcular_h_bloque(h_instancia, secuencia, hash_previo, hash_contenido):
|
||||
"""
|
||||
Calcula el hash del bloque.
|
||||
|
||||
h_bloque = SHA-256(h_instancia:secuencia:hash_previo:hash_contenido)
|
||||
"""
|
||||
import hashlib
|
||||
|
||||
# hash_previo puede ser None para bloque génesis
|
||||
previo = hash_previo or "genesis"
|
||||
|
||||
data = f"{h_instancia}:{secuencia}:{previo}:{hash_contenido}"
|
||||
|
||||
return hashlib.sha256(data.encode()).hexdigest()
|
||||
```
|
||||
|
||||
### hash_contenido
|
||||
|
||||
```python
|
||||
def calcular_hash_contenido(contenido):
|
||||
"""
|
||||
Calcula el hash del contenido.
|
||||
|
||||
hash_contenido = SHA-256(contenido_serializado)
|
||||
"""
|
||||
import hashlib
|
||||
import json
|
||||
|
||||
# Serialización determinista
|
||||
contenido_str = json.dumps(contenido, sort_keys=True, ensure_ascii=False)
|
||||
|
||||
return hashlib.sha256(contenido_str.encode()).hexdigest()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### POST /consolidar
|
||||
|
||||
```http
|
||||
POST /consolidar HTTP/1.1
|
||||
Host: corp.example.com:5054
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Response (éxito)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"h_bloque": "ghi789...",
|
||||
"secuencia": 42,
|
||||
"hash_contenido": "jkl012...",
|
||||
"validaciones": {
|
||||
"M-001": true,
|
||||
"M-002": true,
|
||||
"M-003": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (error)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Validación fallida",
|
||||
"validaciones": {
|
||||
"M-001": true,
|
||||
"M-002": false,
|
||||
"M-003": true
|
||||
},
|
||||
"mensaje": "M-002: hash_previo no existe en cadena"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuración
|
||||
|
||||
### Variables de Entorno
|
||||
|
||||
```bash
|
||||
# /opt/feldman/.env
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=corp
|
||||
DB_USER=feldman
|
||||
DB_PASSWORD=****
|
||||
|
||||
POLL_INTERVAL=5 # Segundos entre polls
|
||||
MAX_BATCH=10 # Elementos por lote
|
||||
MAX_RETRIES=3 # Reintentos antes de rechazar
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados de la Cola
|
||||
|
||||
| Estado | Descripción |
|
||||
|--------|-------------|
|
||||
| pendiente | En espera de procesamiento |
|
||||
| procesando | FELDMAN está validando |
|
||||
| consolidado | Validado y creado bloque/milestone |
|
||||
| rechazado | Falló validación, no se reintentará |
|
||||
| error | Error técnico, puede reintentarse |
|
||||
|
||||
---
|
||||
|
||||
## Auditoría
|
||||
|
||||
Cada validación se registra en `feldman_validaciones`:
|
||||
|
||||
```sql
|
||||
-- Consultar historial de validaciones
|
||||
SELECT
|
||||
h_entrada,
|
||||
regla,
|
||||
resultado,
|
||||
mensaje,
|
||||
validated_at
|
||||
FROM feldman_validaciones
|
||||
WHERE h_entrada = 'abc123...'
|
||||
ORDER BY validated_at;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Futuro: Blockchain
|
||||
|
||||
FELDMAN está diseñado para evolucionar hacia blockchain:
|
||||
|
||||
1. **Actual:** Encadenamiento por hash_previo en PostgreSQL
|
||||
2. **Fase 2:** Merkle tree para verificación eficiente
|
||||
3. **Fase 3:** Smart contract en blockchain (Ethereum/Polygon)
|
||||
|
||||
```
|
||||
Merkle Root
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
Hash(AB) Hash(CD)
|
||||
│ │
|
||||
┌─────┴─────┐ ┌─────┴─────┐
|
||||
│ │ │ │
|
||||
Hash(A) Hash(B) Hash(C) Hash(D)
|
||||
│ │ │ │
|
||||
Bloque A Bloque B Bloque C Bloque D
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoreo
|
||||
|
||||
### Logs
|
||||
```bash
|
||||
docker logs feldman-feldman -f
|
||||
```
|
||||
|
||||
### Consultas de Estado
|
||||
|
||||
```sql
|
||||
-- Elementos pendientes
|
||||
SELECT COUNT(*) FROM feldman_cola WHERE estado = 'pendiente';
|
||||
|
||||
-- Últimas validaciones fallidas
|
||||
SELECT * FROM feldman_validaciones
|
||||
WHERE resultado = false
|
||||
ORDER BY validated_at DESC
|
||||
LIMIT 10;
|
||||
|
||||
-- Bloques creados hoy
|
||||
SELECT COUNT(*) FROM bloques
|
||||
WHERE created_at >= CURRENT_DATE;
|
||||
```
|
||||
-- Últimas validaciones fallidas
|
||||
SELECT * FROM feldman_validaciones
|
||||
WHERE resultado = false
|
||||
ORDER BY validated_at DESC
|
||||
LIMIT 10;
|
||||
|
||||
-- Bloques creados hoy
|
||||
SELECT COUNT(*) FROM bloques
|
||||
WHERE created_at >= CURRENT_DATE;
|
||||
```
|
||||
Reference in New Issue
Block a user