system-docs/03_COMPONENTES/agentes/feldman.md

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

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

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)

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

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

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

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

POST /consolidar HTTP/1.1
Host: corp.example.com:5054
Content-Type: application/json

{
  "tipo": "bloque",
  "h_entrada": "abc123...",
  "h_instancia": "def456...",
  "contenido": {
    "tipo_bloque": "transaccion",
    "monto": 1000,
    "descripcion": "Pago factura #123"
  }
}

Response (éxito)

{
  "success": true,
  "h_bloque": "ghi789...",
  "secuencia": 42,
  "hash_contenido": "jkl012...",
  "validaciones": {
    "M-001": true,
    "M-002": true,
    "M-003": true
  }
}

Response (error)

{
  "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

# /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:

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

docker logs feldman-feldman -f

Consultas de Estado

-- 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;