feldman/README.md

# FELDMAN

![Estado](https://img.shields.io/badge/Estado-PLANIFICADO-yellow)


**Registro consolidado - Sistema TZZR**

## Rol

Contable del sistema. Valida y archiva registros en bloques inmutables.

## Posición en el Flujo

```
MASON ─────────────────┬──► FELDMAN
                       │       │
ALFRED/JARED (OK) ─────┘       │
                               ▼
                    ┌─────────────────────┐
                    │   COLA (24h)        │
                    │   ○ ○ ○ ○ ○        │
                    └─────────┬───────────┘
                              │
                         cada 24h
                              │
                              ▼
                    ┌─────────────────────┐
                    │  BLOQUE INMUTABLE   │
                    │  #1 → #2 → #3 → ... │
                    └─────────────────────┘
```

## Fases

### 1. Cola (24h)
- Registros esperando consolidación
- Usuario puede devolver a MASON
- Configurable

### 2. Bloques
- Registros inmutables
- Hash encadenado
- Preparado para blockchain

## Estructura de Bloque

```json
{
  "numero": 127,
  "id": "sha256-bloque",
  "hash_anterior": "def456...",
  "merkle_root": "789abc...",
  "validado_at": "2025-12-22T00:00:00Z",
  "registros": [...],
  "cantidad": 45
}
```

## Estructura del Contenedor en FELDMAN

Cuando un registro se consolida, FELDMAN anade la seccion `bloque` al contenedor (ver [esquema completo](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/06-contenedor-schema.md)):

```json
{
  "bloque": {
    "id": "sha256-bloque",
    "numero": 127,
    "registro_hash": "sha256-este-registro",
    "merkle_proof": ["sha256-1", "sha256-2", "sha256-3"]
  },

  "estado": {
    "actual": "en_feldman_bloque",
    "historial": [
      {"paso": "clara", "entrada": "...", "salida": "..."},
      {"paso": "mason", "entrada": "...", "salida": "..."},
      {"paso": "feldman_cola", "entrada": "...", "salida": "..."},
      {"paso": "feldman_bloque", "entrada": "...", "procesado_por": "feldman-service"}
    ]
  }
}
```

### Campos del bloque

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `id` | SHA-256 | Hash del bloque completo |
| `numero` | Int | Numero secuencial del bloque |
| `registro_hash` | SHA-256 | Hash de este registro especifico |
| `merkle_proof` | Array | Prueba de inclusion en el arbol Merkle |

### Verificacion

Con `merkle_proof` se puede verificar que un registro pertenece a un bloque sin tener acceso a todos los registros del bloque.

```
              merkle_root
                  │
         ┌───────┴───────┐
         │               │
      hash_ab         hash_cd
         │               │
    ┌────┴────┐     ┌────┴────┐
    │         │     │         │
  reg_a     reg_b reg_c     reg_d
```

### Inmutabilidad

- Una vez consolidado, el registro es **inmutable**
- `estado.actual` cambia a `en_feldman_bloque`
- La seccion `bloque` se anade y nunca cambia
- El hash del registro se incluye en el arbol Merkle

## Arquitectura

Ver documentación completa en [contratos-comunes/architecture](https://git.tzzr.me/tzzr/contratos-comunes/src/branch/main/architecture/04-feldman.md)

---

*Componente del sistema TZZR*